wotann 0.5.0

package/dist/providers/provider-brain.js

@@ -0,0 +1,208 @@
+/**
+ * Provider Brain — unified provider intelligence.
+ * Merges: Cost Oracle + Provider Arbitrage + Model Router + Fallback Chain + Rate Limiter.
+ * Single decision point for: which provider, which model, at what cost, with what fallback.
+ */
+// ── Provider Brain ───────────────────────────────────────
+export class ProviderBrain {
+    healthMap = new Map();
+    budget = {
+        dailyBudget: 10,
+        dailySpent: 0,
+        perQueryMax: 1,
+        preferCheaper: false,
+    };
+    /**
+     * Make a routing decision for a given task.
+     */
+    route(prompt, availableProviders, constraints) {
+        if (constraints) {
+            this.budget = { ...this.budget, ...constraints };
+        }
+        const task = this.classifyTask(prompt);
+        const candidates = this.rankProviders(task, availableProviders);
+        if (candidates.length === 0) {
+            // No available providers. Returning a fake "anthropic" decision
+            // here would silently pin every cold-start request to Anthropic
+            // even when the user has none configured (the v9 META-AUDIT
+            // flagged this as a hidden vendor pin). Surface the real state
+            // so the caller can prompt the user to authenticate or enable a
+            // provider rather than firing a phantom request.
+            throw new Error("ProviderBrain.route: no available providers — caller must prompt the user to configure one");
+        }
+        const best = candidates[0];
+        const alternatives = candidates.slice(1, 4).map((c) => ({
+            provider: c.provider,
+            model: c.model,
+            estimatedCost: c.cost,
+            estimatedLatencyMs: c.latency,
+            tradeoff: this.describeTradeoff(best, c),
+        }));
+        return {
+            provider: best.provider,
+            model: best.model,
+            estimatedCost: best.cost,
+            estimatedLatencyMs: best.latency,
+            reason: best.reason,
+            alternatives,
+            fallbackChain: candidates.slice(1).map((c) => c.provider),
+        };
+    }
+    /**
+     * Update provider health after a request.
+     */
+    updateHealth(provider, latencyMs, success, cost) {
+        const existing = this.healthMap.get(provider) ?? {
+            provider,
+            available: true,
+            rateLimited: false,
+            recentLatencyMs: 1000,
+            recentErrorRate: 0,
+            dailyCost: 0,
+        };
+        // Exponential moving average for latency
+        const alpha = 0.3;
+        const newLatency = alpha * latencyMs + (1 - alpha) * existing.recentLatencyMs;
+        const newErrorRate = alpha * (success ? 0 : 1) + (1 - alpha) * existing.recentErrorRate;
+        this.healthMap.set(provider, {
+            ...existing,
+            recentLatencyMs: newLatency,
+            recentErrorRate: newErrorRate,
+            dailyCost: existing.dailyCost + cost,
+        });
+        this.budget = { ...this.budget, dailySpent: this.budget.dailySpent + cost };
+    }
+    /**
+     * Mark a provider as rate-limited.
+     */
+    markRateLimited(provider, resetsAt) {
+        const existing = this.healthMap.get(provider);
+        if (existing) {
+            this.healthMap.set(provider, { ...existing, rateLimited: true, rateLimitResetsAt: resetsAt });
+        }
+    }
+    /**
+     * Set budget constraints.
+     */
+    setBudget(budget) {
+        this.budget = { ...this.budget, ...budget };
+    }
+    /**
+     * Get budget status.
+     */
+    getBudgetStatus() {
+        const remaining = this.budget.dailyBudget - this.budget.dailySpent;
+        return {
+            remaining,
+            percentUsed: (this.budget.dailySpent / this.budget.dailyBudget) * 100,
+            overBudget: remaining <= 0,
+        };
+    }
+    /**
+     * Get all provider health statuses.
+     */
+    getHealthReport() {
+        return [...this.healthMap.values()];
+    }
+    // ── Private ────────────────────────────────────────────
+    classifyTask(prompt) {
+        const lower = prompt.toLowerCase();
+        let type = "general";
+        let complexity = "moderate";
+        if (lower.includes("research") || lower.includes("find") || lower.includes("search"))
+            type = "research";
+        else if (lower.includes("write") ||
+            lower.includes("implement") ||
+            lower.includes("create") ||
+            lower.includes("build"))
+            type = "code-gen";
+        else if (lower.includes("fix") ||
+            lower.includes("debug") ||
+            lower.includes("why") ||
+            lower.includes("explain"))
+            type = "reasoning";
+        else if (lower.includes("classify") || lower.includes("categorize") || lower.includes("which"))
+            type = "classification";
+        else if (lower.includes("story") || lower.includes("creative") || lower.includes("imagine"))
+            type = "creative";
+        if (prompt.length < 50)
+            complexity = "simple";
+        else if (prompt.length > 500)
+            complexity = "complex";
+        return { type, complexity, estimatedTokens: Math.ceil(prompt.length / 4) * 3 };
+    }
+    rankProviders(task, available) {
+        // Task-type → provider preferences (BEST for each type, not cheapest)
+        const preferences = {
+            reasoning: ["anthropic", "openai", "gemini"],
+            "code-gen": ["anthropic", "openai", "gemini"],
+            research: ["gemini", "openai", "anthropic"],
+            classification: ["gemini", "openai", "anthropic"],
+            creative: ["anthropic", "openai", "gemini"],
+            general: ["anthropic", "openai", "gemini"],
+        };
+        const ordered = preferences[task.type] ?? preferences["general"];
+        const results = [];
+        for (const provider of ordered) {
+            if (!available.includes(provider))
+                continue;
+            const health = this.healthMap.get(provider);
+            if (health?.rateLimited)
+                continue;
+            if (health && health.recentErrorRate > 0.5)
+                continue;
+            const latency = health?.recentLatencyMs ?? 2000;
+            const costPerToken = this.estimateCost(provider, task.estimatedTokens);
+            results.push({
+                provider,
+                model: "auto",
+                cost: costPerToken,
+                latency,
+                reason: `Best ${task.type} provider${health ? ` (${Math.round(latency)}ms avg)` : ""}`,
+            });
+        }
+        // Add any remaining available providers
+        for (const provider of available) {
+            if (!results.some((r) => r.provider === provider)) {
+                results.push({
+                    provider,
+                    model: "auto",
+                    cost: this.estimateCost(provider, task.estimatedTokens),
+                    latency: this.healthMap.get(provider)?.recentLatencyMs ?? 3000,
+                    reason: "Available fallback",
+                });
+            }
+        }
+        // Sort: budget-aware ranking
+        if (this.budget.preferCheaper) {
+            results.sort((a, b) => a.cost - b.cost);
+        }
+        return results;
+    }
+    estimateCost(provider, tokens) {
+        const costPerMillion = {
+            anthropic: 15,
+            openai: 10,
+            gemini: 7,
+            ollama: 0,
+            free: 0,
+            azure: 12,
+            bedrock: 15,
+            vertex: 7,
+            codex: 0,
+            copilot: 0,
+            huggingface: 1,
+        };
+        return ((costPerMillion[provider] ?? 10) * tokens) / 1_000_000;
+    }
+    describeTradeoff(best, alt) {
+        const costDiff = ((alt.cost - best.cost) / Math.max(best.cost, 0.0001)) * 100;
+        const latencyDiff = ((alt.latency - best.latency) / Math.max(best.latency, 1)) * 100;
+        if (costDiff < -20)
+            return `${Math.abs(Math.round(costDiff))}% cheaper`;
+        if (latencyDiff < -20)
+            return `${Math.abs(Math.round(latencyDiff))}% faster`;
+        return `${alt.provider} alternative`;
+    }
+}
+//# sourceMappingURL=provider-brain.js.map

package/dist/providers/provider-brain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-brain.js","sourceRoot":"","sources":["../../src/providers/provider-brain.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA+CH,4DAA4D;AAE5D,MAAM,OAAO,aAAa;IACP,SAAS,GAAsC,IAAI,GAAG,EAAE,CAAC;IAClE,MAAM,GAAsB;QAClC,WAAW,EAAE,EAAE;QACf,UAAU,EAAE,CAAC;QACb,WAAW,EAAE,CAAC;QACd,aAAa,EAAE,KAAK;KACrB,CAAC;IAEF;;OAEG;IACH,KAAK,CACH,MAAc,EACd,kBAA2C,EAC3C,WAAwC;QAExC,IAAI,WAAW,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,WAAW,EAAE,CAAC;QACnD,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;QAEhE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,gEAAgE;YAChE,gEAAgE;YAChE,4DAA4D;YAC5D,+DAA+D;YAC/D,gEAAgE;YAChE,iDAAiD;YACjD,MAAM,IAAI,KAAK,CACb,4FAA4F,CAC7F,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAE,CAAC;QAC5B,MAAM,YAAY,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACtD,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,aAAa,EAAE,CAAC,CAAC,IAAI;YACrB,kBAAkB,EAAE,CAAC,CAAC,OAAO;YAC7B,QAAQ,EAAE,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC;SACzC,CAAC,CAAC,CAAC;QAEJ,OAAO;YACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,aAAa,EAAE,IAAI,CAAC,IAAI;YACxB,kBAAkB,EAAE,IAAI,CAAC,OAAO;YAChC,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,YAAY;YACZ,aAAa,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;SAC1D,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,QAAsB,EAAE,SAAiB,EAAE,OAAgB,EAAE,IAAY;QACpF,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI;YAC/C,QAAQ;YACR,SAAS,EAAE,IAAI;YACf,WAAW,EAAE,KAAK;YAClB,eAAe,EAAE,IAAI;YACrB,eAAe,EAAE,CAAC;YAClB,SAAS,EAAE,CAAC;SACb,CAAC;QAEF,yCAAyC;QACzC,MAAM,KAAK,GAAG,GAAG,CAAC;QAClB,MAAM,UAAU,GAAG,KAAK,GAAG,SAAS,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,QAAQ,CAAC,eAAe,CAAC;QAC9E,MAAM,YAAY,GAAG,KAAK,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,QAAQ,CAAC,eAAe,CAAC;QAExF,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE;YAC3B,GAAG,QAAQ;YACX,eAAe,EAAE,UAAU;YAC3B,eAAe,EAAE,YAAY;YAC7B,SAAS,EAAE,QAAQ,CAAC,SAAS,GAAG,IAAI;SACrC,CAAC,CAAC;QAEH,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,IAAI,EAAE,CAAC;IAC9E,CAAC;IAED;;OAEG;IACH,eAAe,CAAC,QAAsB,EAAE,QAAgB;QACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9C,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,GAAG,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,EAAE,QAAQ,EAAE,CAAC,CAAC;QAChG,CAAC;IACH,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,MAAkC;QAC1C,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IAC9C,CAAC;IAED;;OAEG;IACH,eAAe;QACb,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC;QACnE,OAAO;YACL,SAAS;YACT,WAAW,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,GAAG;YACrE,UAAU,EAAE,SAAS,IAAI,CAAC;SAC3B,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,0DAA0D;IAElD,YAAY,CAAC,MAAc;QACjC,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;QACnC,IAAI,IAAI,GAA+B,SAAS,CAAC;QACjD,IAAI,UAAU,GAAqC,UAAU,CAAC;QAE9D,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAClF,IAAI,GAAG,UAAU,CAAC;aACf,IACH,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;YACvB,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC;YAC3B,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;YACxB,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;YAEvB,IAAI,GAAG,UAAU,CAAC;aACf,IACH,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;YACrB,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;YACvB,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;YACrB,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC;YAEzB,IAAI,GAAG,WAAW,CAAC;aAChB,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC;YAC5F,IAAI,GAAG,gBAAgB,CAAC;aACrB,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC;YACzF,IAAI,GAAG,UAAU,CAAC;QAEpB,IAAI,MAAM,CAAC,MAAM,GAAG,EAAE;YAAE,UAAU,GAAG,QAAQ,CAAC;aACzC,IAAI,MAAM,CAAC,MAAM,GAAG,GAAG;YAAE,UAAU,GAAG,SAAS,CAAC;QAErD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,eAAe,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;IACjF,CAAC;IAEO,aAAa,CACnB,IAAwB,EACxB,SAAkC;QAElC,sEAAsE;QACtE,MAAM,WAAW,GAA4C;YAC3D,SAAS,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC;YAC5C,UAAU,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC;YAC7C,QAAQ,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,CAAC;YAC3C,cAAc,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,CAAC;YACjD,QAAQ,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC;YAC3C,OAAO,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC;SAC3C,CAAC;QAEF,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,SAAS,CAAE,CAAC;QAClE,MAAM,OAAO,GAMP,EAAE,CAAC;QAET,KAAK,MAAM,QAAQ,IAAI,OAAO,EAAE,CAAC;YAC/B,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAAE,SAAS;YAE5C,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC5C,IAAI,MAAM,EAAE,WAAW;gBAAE,SAAS;YAClC,IAAI,MAAM,IAAI,MAAM,CAAC,eAAe,GAAG,GAAG;gBAAE,SAAS;YAErD,MAAM,OAAO,GAAG,MAAM,EAAE,eAAe,IAAI,IAAI,CAAC;YAChD,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;YAEvE,OAAO,CAAC,IAAI,CAAC;gBACX,QAAQ;gBACR,KAAK,EAAE,MAAM;gBACb,IAAI,EAAE,YAAY;gBAClB,OAAO;gBACP,MAAM,EAAE,QAAQ,IAAI,CAAC,IAAI,YAAY,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE;aACvF,CAAC,CAAC;QACL,CAAC;QAED,wCAAwC;QACxC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,EAAE,CAAC;gBAClD,OAAO,CAAC,IAAI,CAAC;oBACX,QAAQ;oBACR,KAAK,EAAE,MAAM;oBACb,IAAI,EAAE,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,CAAC;oBACvD,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,eAAe,IAAI,IAAI;oBAC9D,MAAM,EAAE,oBAAoB;iBAC7B,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,6BAA6B;QAC7B,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;YAC9B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1C,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAEO,YAAY,CAAC,QAAsB,EAAE,MAAc;QACzD,MAAM,cAAc,GAA2B;YAC7C,SAAS,EAAE,EAAE;YACb,MAAM,EAAE,EAAE;YACV,MAAM,EAAE,CAAC;YACT,MAAM,EAAE,CAAC;YACT,IAAI,EAAE,CAAC;YACP,KAAK,EAAE,EAAE;YACT,OAAO,EAAE,EAAE;YACX,MAAM,EAAE,CAAC;YACT,KAAK,EAAE,CAAC;YACR,OAAO,EAAE,CAAC;YACV,WAAW,EAAE,CAAC;SACf,CAAC;QACF,OAAO,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC;IACjE,CAAC;IAEO,gBAAgB,CACtB,IAAuC,EACvC,GAA8D;QAE9D,MAAM,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,GAAG,GAAG,CAAC;QAC9E,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;QAErF,IAAI,QAAQ,GAAG,CAAC,EAAE;YAAE,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,WAAW,CAAC;QACxE,IAAI,WAAW,GAAG,CAAC,EAAE;YAAE,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,UAAU,CAAC;QAC7E,OAAO,GAAG,GAAG,CAAC,QAAQ,cAAc,CAAC;IACvC,CAAC;CACF"}

package/dist/providers/provider-ladder.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Canonical provider priority ladder — V9 Tier 6 T6.4.
+ *
+ * When a user runs `wotann init` with nothing configured, WOTANN walks
+ * this ladder top-down and picks the first available option. The
+ * ordering reflects V9's subscription-first strategy:
+ *
+ *   1. Subscription providers (zero marginal cost to user)
+ *   2. Free-tier cloud APIs (no credit card)
+ *   3. BYOK cloud APIs (pay-per-token)
+ *   4. Local models (fully private)
+ *
+ * The ladder is a PURE DATA STRUCTURE — no side effects. Callers query
+ * it via `selectFirstAvailable(availability)` where the availability map
+ * is built by the onboarding wizard's detector passes. The detector
+ * decisions live in `hardware-detect.ts` (local feasibility),
+ * `claude-cli-backend.ts` (Claude CLI presence), and similar.
+ *
+ * NOTE (V9 Wave 6.9 / W6.9 AH): the LM Studio rung's `probe` key
+ * `lm-studio-local` is a hook for a future detector. The dedicated
+ * `lm-studio-adapter.ts` was deleted as a dead orphan — per the user
+ * directive captured in `first-run-runner-factory.ts:37`, local rungs
+ * go through the generic OpenAI-compat path (Ollama by default). If
+ * an LM Studio detector ever lands, point it at the openai-compat
+ * adapter with `baseUrl=http://localhost:1234/v1` and a sentinel
+ * apiKey — no bespoke adapter required.
+ *
+ * WOTANN quality bars:
+ * - QB #7 per-call state: the ladder is a `readonly` const. The
+ *   caller builds a fresh availability snapshot every time.
+ * - QB #11 sibling-site scan: consumers will be the Ink wizard
+ *   (T6.2) + a CLI flag-less `wotann init` default. Neither wired
+ *   yet; this module ships the data first so both consumers can
+ *   use it when their scope lands.
+ */
+import type { ProviderName } from "../core/types.js";
+export type ProviderRungCategory = "subscription" | "free-tier" | "free-aggregator" | "byok" | "local" | "advanced";
+/**
+ * One rung on the ladder. `id` is WOTANN's canonical provider name
+ * (the string used throughout the registry + cost tracker). `probe`
+ * is the key a caller looks up in the availability map — kept as
+ * string so detectors can report arbitrary capability keys without
+ * polluting `ProviderName`.
+ */
+export interface ProviderRung {
+    readonly rank: number;
+    readonly id: ProviderName;
+    readonly probe: string;
+    readonly category: ProviderRungCategory;
+    readonly label: string;
+    /** Human-readable cost summary for the onboarding UI. */
+    readonly costNote: string;
+    /**
+     * True when this rung can be selected WITHOUT a credit card.
+     * Used by the onboarding wizard's "free options only" filter.
+     */
+    readonly noCreditCard: boolean;
+    /**
+     * True when this rung runs ENTIRELY on-device — never sends data
+     * to a third party. Used by "fully private" filter.
+     */
+    readonly fullyLocal: boolean;
+}
+/**
+ * Source-verified V9 T6.4 ordering. Each rung's `rank` is the
+ * priority order the wizard walks top-down; first rung with
+ * `availability[rung.probe] === true` is selected.
+ */
+export declare const PROVIDER_LADDER: readonly ProviderRung[];
+/**
+ * Availability snapshot built by the onboarding wizard. Map from a
+ * rung's `probe` string to boolean — `true` means the rung's
+ * prerequisites are satisfied (binary present / API key set /
+ * server responding on expected port).
+ */
+export type ProviderAvailability = Readonly<Record<string, boolean>>;
+/**
+ * Walk the ladder top-down and return the first rung whose `probe`
+ * key is `true` in the availability map. Returns `null` when nothing
+ * on the ladder is available (caller shows "no providers available —
+ * here are install links").
+ */
+export declare function selectFirstAvailable(availability: ProviderAvailability): ProviderRung | null;
+/**
+ * Filter the ladder down to rungs that satisfy the user's declared
+ * constraints. Used by the wizard's "show me only free options" /
+ * "show me only local options" toggles.
+ */
+export declare function filterLadder(filters?: {
+    readonly noCreditCardOnly?: boolean;
+    readonly fullyLocalOnly?: boolean;
+    readonly categories?: readonly ProviderRungCategory[];
+}): readonly ProviderRung[];
+/**
+ * Group the ladder by category — the wizard displays rungs under
+ * headings ("Subscriptions", "Free cloud", "BYOK", "Local",
+ * "Advanced"). Preserves rank order within each category.
+ */
+export declare function groupByCategory(): Readonly<Record<ProviderRungCategory, readonly ProviderRung[]>>;
+//# sourceMappingURL=provider-ladder.d.ts.map

package/dist/providers/provider-ladder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-ladder.d.ts","sourceRoot":"","sources":["../../src/providers/provider-ladder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIrD,MAAM,MAAM,oBAAoB,GAC5B,cAAc,GACd,WAAW,GACX,iBAAiB,GACjB,MAAM,GACN,OAAO,GACP,UAAU,CAAC;AAEf;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAID;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,YAAY,EAiIzC,CAAC;AAIX;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAErE;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,oBAAoB,GAAG,YAAY,GAAG,IAAI,CAK5F;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,OAAO,GAAE;IACP,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAClD,GACL,SAAS,YAAY,EAAE,CAOzB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,QAAQ,CAAC,MAAM,CAAC,oBAAoB,EAAE,SAAS,YAAY,EAAE,CAAC,CAAC,CAajG"}

package/dist/providers/provider-ladder.js

@@ -0,0 +1,220 @@
+/**
+ * Canonical provider priority ladder — V9 Tier 6 T6.4.
+ *
+ * When a user runs `wotann init` with nothing configured, WOTANN walks
+ * this ladder top-down and picks the first available option. The
+ * ordering reflects V9's subscription-first strategy:
+ *
+ *   1. Subscription providers (zero marginal cost to user)
+ *   2. Free-tier cloud APIs (no credit card)
+ *   3. BYOK cloud APIs (pay-per-token)
+ *   4. Local models (fully private)
+ *
+ * The ladder is a PURE DATA STRUCTURE — no side effects. Callers query
+ * it via `selectFirstAvailable(availability)` where the availability map
+ * is built by the onboarding wizard's detector passes. The detector
+ * decisions live in `hardware-detect.ts` (local feasibility),
+ * `claude-cli-backend.ts` (Claude CLI presence), and similar.
+ *
+ * NOTE (V9 Wave 6.9 / W6.9 AH): the LM Studio rung's `probe` key
+ * `lm-studio-local` is a hook for a future detector. The dedicated
+ * `lm-studio-adapter.ts` was deleted as a dead orphan — per the user
+ * directive captured in `first-run-runner-factory.ts:37`, local rungs
+ * go through the generic OpenAI-compat path (Ollama by default). If
+ * an LM Studio detector ever lands, point it at the openai-compat
+ * adapter with `baseUrl=http://localhost:1234/v1` and a sentinel
+ * apiKey — no bespoke adapter required.
+ *
+ * WOTANN quality bars:
+ * - QB #7 per-call state: the ladder is a `readonly` const. The
+ *   caller builds a fresh availability snapshot every time.
+ * - QB #11 sibling-site scan: consumers will be the Ink wizard
+ *   (T6.2) + a CLI flag-less `wotann init` default. Neither wired
+ *   yet; this module ships the data first so both consumers can
+ *   use it when their scope lands.
+ */
+// ── The ladder ────────────────────────────────────────────────────────────
+/**
+ * Source-verified V9 T6.4 ordering. Each rung's `rank` is the
+ * priority order the wizard walks top-down; first rung with
+ * `availability[rung.probe] === true` is selected.
+ */
+export const PROVIDER_LADDER = [
+    {
+        rank: 1,
+        id: "anthropic",
+        probe: "claude-cli",
+        category: "subscription",
+        label: "Claude Max/Pro (via Claude Code CLI)",
+        costNote: "subscription ($20-200/mo), no per-query cost",
+        noCreditCard: false,
+        fullyLocal: false,
+    },
+    {
+        rank: 2,
+        id: "codex",
+        probe: "codex-cli",
+        category: "subscription",
+        label: "ChatGPT Plus/Pro (via Codex CLI session)",
+        costNote: "subscription ($20-60/mo), uses existing login",
+        noCreditCard: false,
+        fullyLocal: false,
+    },
+    {
+        rank: 3,
+        id: "copilot",
+        probe: "gh-token",
+        category: "subscription",
+        label: "GitHub Copilot",
+        costNote: "Free tier (2K completions/mo) or $10-39/mo paid",
+        noCreditCard: true, // free tier
+        fullyLocal: false,
+    },
+    {
+        rank: 4,
+        id: "openrouter",
+        probe: "groq-free",
+        category: "free-tier",
+        label: "Groq free tier (Llama 3.3 70B @ 315 tok/s)",
+        costNote: "1000 req/day free, no CC",
+        noCreditCard: true,
+        fullyLocal: false,
+    },
+    {
+        rank: 5,
+        id: "gemini",
+        probe: "gemini-free",
+        category: "free-tier",
+        label: "Gemini free tier (1.5M token context)",
+        costNote: "1500 req/day free, no CC",
+        noCreditCard: true,
+        fullyLocal: false,
+    },
+    {
+        rank: 6,
+        id: "openrouter",
+        probe: "cerebras-free",
+        category: "free-tier",
+        label: "Cerebras free tier (fast inference)",
+        costNote: "60K tokens/min free, no CC",
+        noCreditCard: true,
+        fullyLocal: false,
+    },
+    {
+        rank: 7,
+        id: "openrouter",
+        probe: "deepseek-free",
+        category: "free-tier",
+        label: "DeepSeek (500K free/day + paid)",
+        costNote: "500K tokens/day free, then $0.14/M cached",
+        noCreditCard: true,
+        fullyLocal: false,
+    },
+    {
+        rank: 8,
+        id: "anthropic",
+        probe: "anthropic-byok",
+        category: "byok",
+        label: "Anthropic API (BYOK)",
+        costNote: "pay-per-token, $3-15 per million",
+        noCreditCard: false,
+        fullyLocal: false,
+    },
+    {
+        rank: 9,
+        id: "openai",
+        probe: "openai-byok",
+        category: "byok",
+        label: "OpenAI API (BYOK)",
+        costNote: "pay-per-token, $2.50-$60 per million depending on model",
+        noCreditCard: false,
+        fullyLocal: false,
+    },
+    {
+        rank: 10,
+        id: "ollama",
+        probe: "ollama-local",
+        category: "local",
+        label: "Ollama (local, private)",
+        costNote: "free, runs on your machine",
+        noCreditCard: true,
+        fullyLocal: true,
+    },
+    // V9 §T6.4 — OpenRouter is a BYOK aggregator that rotates a small
+    // free-tier across third-party hosts (Mistral 7B Instruct,
+    // Llama 3.1 8B, Gemma 2 9B, etc.). Spec line 1037 listed it at
+    // rank 11 — we keep it at #11 here so the wizard prefers a
+    // free-aggregator rung BEFORE LM-Studio's local model (which
+    // requires a 4-8 GB local model already downloaded). The rung is
+    // tagged with the bespoke `free-aggregator` category so the
+    // grouping UI keeps it distinct from single-provider free tiers.
+    {
+        rank: 11,
+        id: "openrouter",
+        probe: "openrouter-free",
+        category: "free-aggregator",
+        label: "OpenRouter (free aggregator — Mistral 7B, Llama 3.1 8B, Gemma 2 9B)",
+        costNote: "rotating free tier, no CC; paid models behind the same key",
+        noCreditCard: true,
+        fullyLocal: false,
+    },
+    {
+        rank: 12,
+        id: "lm-studio",
+        probe: "lm-studio-local",
+        category: "local",
+        label: "LM Studio (local, private)",
+        costNote: "free, runs on your machine",
+        noCreditCard: true,
+        fullyLocal: true,
+    },
+];
+/**
+ * Walk the ladder top-down and return the first rung whose `probe`
+ * key is `true` in the availability map. Returns `null` when nothing
+ * on the ladder is available (caller shows "no providers available —
+ * here are install links").
+ */
+export function selectFirstAvailable(availability) {
+    for (const rung of PROVIDER_LADDER) {
+        if (availability[rung.probe] === true)
+            return rung;
+    }
+    return null;
+}
+/**
+ * Filter the ladder down to rungs that satisfy the user's declared
+ * constraints. Used by the wizard's "show me only free options" /
+ * "show me only local options" toggles.
+ */
+export function filterLadder(filters = {}) {
+    return PROVIDER_LADDER.filter((r) => {
+        if (filters.noCreditCardOnly && !r.noCreditCard)
+            return false;
+        if (filters.fullyLocalOnly && !r.fullyLocal)
+            return false;
+        if (filters.categories && !filters.categories.includes(r.category))
+            return false;
+        return true;
+    });
+}
+/**
+ * Group the ladder by category — the wizard displays rungs under
+ * headings ("Subscriptions", "Free cloud", "BYOK", "Local",
+ * "Advanced"). Preserves rank order within each category.
+ */
+export function groupByCategory() {
+    const groups = {
+        subscription: [],
+        "free-tier": [],
+        "free-aggregator": [],
+        byok: [],
+        local: [],
+        advanced: [],
+    };
+    for (const r of PROVIDER_LADDER) {
+        groups[r.category].push(r);
+    }
+    return groups;
+}
+//# sourceMappingURL=provider-ladder.js.map

package/dist/providers/provider-ladder.js.map

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