brito-cli 0.6.4 → 0.7.0

package/dist/desktop/serve.js

@@ -10,20 +10,25 @@ import "../tools/delegate.js";
 import "../tools/plan.js";
 import "../tools/skills.js";
 import { Agent } from "../agent/loop.js";
-import { ClaudeSession, hasClaudeCli } from "../agent/claude-cli.js";
+import { ClaudeSession, hasClaudeCli, historyForFallback } from "../agent/claude-cli.js";
 import { startApprovalServer } from "../agent/approval.js";
 import { loadProjectAgents } from "../agent/agents.js";
 import { buildSystemPrompt, graphStatsLine } from "../agent/prompt.js";
-import { GraphStore } from "../graph/store.js";
+import { openGraphAfterClaude } from "../graph/store.js";
 import { indexProject } from "../graph/indexer.js";
-import { DEFAULT_MODEL, initialEffort, initialModel, isEffort, MODEL_ALIASES } from "../model.js";
+import { initialEffort, initialModel, isEffort, loadProfiles, MODEL_ALIASES } from "../model.js";
+import { FALLBACK_PROFILE, NO_ANTHROPIC, fallbackStatus, openEngine } from "../engine.js";
+import { activateFallback, chooseModel, cliShouldFallBack, fallbackWarning, newFallbackState, renderFallback, retryPrompt } from "../provider/fallback.js";
+import { contextWindowFor, resolveModel } from "../provider/resolve.js";
 import { PLAN_NOTE, perms } from "../permissions.js";
 import { skillsIndex } from "../skills/store.js";
 /**
  * Backend do app desktop, controlado por JSON em linhas.
  * stdin  → {t:"send",text} {t:"abort"} {t:"approve",id,allow} {t:"config",model?,effort?,mode?} {t:"reset"} {t:"quit"}
  * stdout → linhas "@@{json}" (qualquer outra linha, como logs perdidos, a janela ignora).
- * Motor: com ANTHROPIC_API_KEY usa a API direta (como o `brito` no terminal); sem ela, o `claude` CLI (assinatura).
+ * Motor: perfil de endpoint (ex.: Qwen) ou ANTHROPIC_API_KEY usam o loop próprio (como o `brito` no terminal); sem
+ * nada disso, o `claude` CLI (assinatura). Se o Claude cai por conta/capacidade (ou nem há conta), segue no qwen.
+ * `/fallback` enviado como texto responde o estado do fallback sem passar pelo modelo.
  */
 const MARK = "@@";
 const emit = (ev) => process.stdout.write(MARK + JSON.stringify(ev) + "\n");
@@ -39,7 +44,7 @@ const sink = {
     warn: (msg) => emit({ t: "warn", msg }),
     error: (msg) => emit({ t: "error", msg }),
 };
-const CTX_WINDOW = Number(process.env.BRITO_CONTEXT_WINDOW ?? 200_000);
+const apiLabel = (m) => (resolveModel(m).kind === "openai" ? "endpoint" : "API Anthropic");
 export async function serveDesktop(root, resumeId) {
     const pending = new Map();
     const ask = (text, opts) => perms.mode === "bypass" && !opts?.force ? Promise.resolve(true) : new Promise((resolve) => {
@@ -49,21 +54,26 @@ export async function serveDesktop(root, resumeId) {
     });
     // Na pasta pessoal (projeto "Home") indexar tudo seria enorme e inútil: sem índice ali.
     const isHome = path.resolve(root) === path.resolve(os.homedir());
-    const useApi = !!process.env.ANTHROPIC_API_KEY;
-    if (!useApi && !hasClaudeCli()) {
-        emit({ t: "error", msg: "Sem acesso ao modelo: defina ANTHROPIC_API_KEY (no seu shell) ou instale o Claude Code e rode `claude` → /login." });
+    for (const e of loadProfiles().errors)
+        emit({ t: "warn", msg: e });
+    const startModel = initialModel();
+    const opening = openEngine(startModel, process.env, hasClaudeCli);
+    if (opening.kind === "error") {
+        const msg = resolveModel(startModel).kind === "openai" ? opening.message : opening.message.replace(/^Defina ANTHROPIC_API_KEY/, "Sem acesso ao modelo: defina ANTHROPIC_API_KEY (no seu shell)");
+        emit({ t: "error", msg });
         process.exit(1);
     }
     loadProjectAgents(root);
     let engine;
     let syms = 0, notes = 0;
     let closeApproval = () => { };
-    if (useApi) {
-        // API direta: o grafo fica aberto neste processo (sem servidor MCP), como no `brito` do terminal.
+    /** Loop próprio (API direta ou endpoint): o grafo fica aberto neste processo (sem servidor MCP), como no `brito` do terminal. */
+    const buildApiEngine = async (model, o = {}) => {
         // No Home o banco vai para ~/.brito/home-graph, para não criar .brito dentro da pasta pessoal.
         const graphRoot = isHome ? path.join(os.homedir(), ".brito", "home-graph") : root;
         fs.mkdirSync(graphRoot, { recursive: true });
-        const graph = await GraphStore.open(graphRoot);
+        // Na troca, o servidor MCP do claude pode ainda estar soltando o banco.
+        const graph = await openGraphAfterClaude(graphRoot);
         const sync = async () => { if (!isHome)
             syms = (await indexProject(root, graph)).symbols; };
         emit({ t: "info", msg: "sincronizando grafo…" });
@@ -77,16 +87,41 @@ export async function serveDesktop(root, resumeId) {
             notes = Number((await graph.run("MATCH (s:Note) RETURN count(s) AS n"))[0].n);
         }
         catch { /* sem notas */ }
-        const ctx = { root, graph, ask, sync, dirty: false, loadedSkills: new Set() };
-        const agent = new Agent(() => buildSystemPrompt(root, graphStatsLine(syms, notes, "now"), skillsIndex(root)) + (perms.mode === "plan" ? PLAN_NOTE : ""), ctx, { model: initialModel(), sink });
+        const ctx = { root, graph, ask, sync, dirty: false, loadedSkills: o.loadedSkills ?? new Set(), model: () => agent.model };
+        const fallback = o.fallback ?? newFallbackState(model);
+        const agent = new Agent(() => buildSystemPrompt(root, graphStatsLine(syms, notes, "now"), skillsIndex(root)) + (perms.mode === "plan" ? PLAN_NOTE : ""), ctx, { model, sink, fallback });
+        if (o.messages)
+            agent.messages = o.messages;
+        if (o.effort)
+            agent.effort = o.effort;
         let ac = null;
         const id = randomUUID();
-        if (resumeId)
-            emit({ t: "info", msg: "No modo API o histórico da conversa não é retomado ao reabrir; a tela mostra o que já foi dito, mas o modelo recomeça." });
-        engine = {
-            kind: "api", sessionId: id, effort: "",
+        return {
+            kind: "api", effort: "", fallback,
+            // Depois da troca o id segue o do claude: a janela o guarda para retomar a conversa ao reabrir.
+            get sessionId() { return o.back?.engine.sessionId ?? id; },
             get model() { return agent.model; }, set model(m) { agent.model = m; },
-            setModel: (m) => { agent.model = m; },
+            engineLabel: o.engineLabel ?? apiLabel,
+            setModel: (m) => {
+                const target = m || initialModel();
+                // Sem ANTHROPIC_API_KEY o Claude não roda neste loop: volta ao claude CLI de onde veio, ou segue no qwen.
+                if (resolveModel(target).kind === "anthropic" && !process.env.ANTHROPIC_API_KEY?.trim()) {
+                    if (o.back) {
+                        engine = o.back.engine;
+                        engine.setModel(m);
+                        if (!m)
+                            chooseModel(fallback, target); // com m vazio o claude não escolhe (o modelo dele vira o placeholder)
+                        o.back.release(graph.close().catch(() => { }));
+                        o.back.handoff(agent.unsentTurns.splice(0), agent.model);
+                        sink.info("de volta ao claude CLI: o que foi feito no qwen segue no próximo pedido");
+                    }
+                    else if (m)
+                        sink.warn(`o ${m} precisa de ANTHROPIC_API_KEY (ou do claude CLI); seguindo no ${agent.model}`);
+                    return;
+                }
+                agent.model = target;
+                chooseModel(fallback, target);
+            },
             async send(text) {
                 ac = new AbortController();
                 sink.turnStart();
@@ -104,10 +139,30 @@ export async function serveDesktop(root, resumeId) {
                 }
             },
             abort: () => ac?.abort(),
-            reset: () => { agent.messages = []; agent.contextTokens = 0; agent.recentTurns = []; agent.lastTurn = null; },
-            stats: () => ({ usage: agent.usage, contextTokens: agent.contextTokens, contextWindow: CTX_WINDOW, costUsd: 0 }),
+            reset: () => {
+                agent.messages = [];
+                agent.contextTokens = 0;
+                agent.recentTurns = [];
+                agent.unsentTurns = [];
+                agent.lastTurn = null;
+                o.back?.engine.reset(); // senão a volta ao claude retomaria (--resume) a conversa limpa
+            },
+            stats: () => ({ usage: agent.usage, contextTokens: agent.contextTokens, contextWindow: contextWindowFor(agent.model), costUsd: o.back?.costUsd() ?? 0 }),
             close: async () => { await graph.close(); },
         };
+    };
+    if (opening.kind !== "claude") {
+        if (resumeId)
+            emit({ t: "info", msg: "No modo API o histórico da conversa não é retomado ao reabrir; a tela mostra o que já foi dito, mas o modelo recomeça." });
+        if (opening.kind === "fallback") {
+            // Claude sem conta nenhuma, com o fallback pronto: a sessão já nasce no qwen (com aviso, nunca em silêncio).
+            emit({ t: "warn", msg: `⚠ ${NO_ANTHROPIC} (sem ANTHROPIC_API_KEY e sem o claude CLI) — abrindo no ${opening.label}. Envie /fallback para detalhes.` });
+            const fallback = newFallbackState(startModel);
+            activateFallback(fallback, NO_ANTHROPIC);
+            engine = await buildApiEngine(FALLBACK_PROFILE, { fallback, engineLabel: () => NO_ANTHROPIC });
+        }
+        else
+            engine = await buildApiEngine(startModel);
     }
     else {
         const approval = startApprovalServer({ ask });
@@ -115,7 +170,7 @@ export async function serveDesktop(root, resumeId) {
         // O banco aceita um único processo com escrita: indexa, lê as stats e solta o banco para o servidor MCP.
         if (!isHome)
             try {
-                const graph = await GraphStore.open(root);
+                const graph = await openGraphAfterClaude(root);
                 emit({ t: "info", msg: "sincronizando grafo…" });
                 await indexProject(root, graph);
                 syms = Number((await graph.run("MATCH (s:Symbol) RETURN count(s) AS n"))[0].n);
@@ -133,22 +188,60 @@ export async function serveDesktop(root, resumeId) {
         });
         if (resumeId)
             session.resume(resumeId);
+        let resumed = !!resumeId; // até o primeiro reset
         session.effort = initialEffort();
-        engine = {
-            kind: "claude",
+        const fallback = newFallbackState(session.requestedModel || session.model);
+        /** Fechamento do grafo do modo API na volta para cá (ver `back.release`). */
+        let graphReleased = Promise.resolve();
+        const claude = {
+            kind: "claude", fallback,
             get sessionId() { return session.sessionId; },
             get model() { return session.model; },
             get effort() { return session.effort; }, set effort(e) { session.effort = e; },
-            setModel: (m) => { session.requestedModel = m; session.model = m || "claude (assinatura)"; },
-            send: async (text) => { await session.send(text); },
+            engineLabel: () => "claude CLI · assinatura",
+            setModel: (m) => { session.requestedModel = m; session.model = m || "claude (assinatura)"; if (m)
+                chooseModel(fallback, m); },
+            send: async (text) => {
+                await graphReleased;
+                if (await session.send(text))
+                    return;
+                // Caiu por conta/capacidade: monta o loop próprio no qwen com a conversa do claude e refaz o pedido nele.
+                const status = fallbackStatus(fallback.primary, process.env);
+                const f = session.lastFailure;
+                if (!f || !status.ready || !cliShouldFallBack(f, fallback, status))
+                    return;
+                sink.warn(fallbackWarning(f.kind, f.message, status.label));
+                // `resume` só reaproveita o id: o que veio antes da reabertura está na sessão do claude, não em `allTurns`.
+                if (resumed)
+                    sink.warn(`a conversa anterior à reabertura ficou no claude CLI: o ${status.label} herda só o que foi dito desde então`);
+                let api;
+                try {
+                    api = await buildApiEngine(status.name, {
+                        fallback, engineLabel: () => "claude CLI · assinatura", messages: historyForFallback(session.allTurns),
+                        effort: session.effort, loadedSkills: session.loadedSkills, back: {
+                            engine: claude, costUsd: () => session.costUsd, handoff: (turns, label) => session.handoff(turns, label),
+                            release: (closing) => { graphReleased = closing; },
+                        },
+                    });
+                }
+                catch (e) {
+                    sink.error(`não consegui abrir o ${status.label}: ${e?.message ?? e}`);
+                    return;
+                }
+                activateFallback(fallback, `${f.kind} (${f.message})`);
+                engine = api;
+                ready();
+                await api.send(retryPrompt(text, resumed));
+            },
             abort: () => session.abort(),
-            reset: () => session.reset(),
+            reset: () => { session.reset(); resumed = false; },
             stats: () => ({ usage: session.usage, contextTokens: session.contextTokens, contextWindow: session.contextWindow, costUsd: session.costUsd }),
             close: async () => { },
         };
+        engine = claude;
     }
     let busy = false;
-    const ready = () => emit({ t: "ready", engine: engine.kind, sessionId: engine.sessionId, model: engine.model, effort: engine.effort, mode: perms.mode, symbols: syms, notes, root });
+    const ready = () => emit({ t: "ready", engine: engine.kind, sessionId: engine.sessionId, model: engine.model, effort: engine.effort, mode: perms.mode, symbols: syms, notes, root, fallback: engine.fallback.active });
     ready();
     const rl = readline.createInterface({ input: process.stdin });
     const quit = async () => { closeApproval(); try {
@@ -168,13 +261,23 @@ export async function serveDesktop(root, resumeId) {
             case "send": {
                 if (busy)
                     return emit({ t: "warn", msg: "já existe um turno em andamento" });
+                if (String(m.text ?? "").trim() === "/fallback") {
+                    const fb = engine.fallback;
+                    const primary = fb.active ? fb.primary : engine.model;
+                    const lines = renderFallback(fb, engine.model, engine.engineLabel(primary), fallbackStatus(primary, process.env));
+                    sink.turnStart();
+                    sink.text("```\n" + lines.join("\n") + "\n```");
+                    sink.textEnd();
+                    sink.turnEnd(true);
+                    return;
+                }
                 busy = true;
                 try {
                     await engine.send(String(m.text ?? ""));
                 }
                 finally {
                     busy = false;
-                    emit({ t: "usage", ...engine.stats(), model: engine.model, sessionId: engine.sessionId });
+                    emit({ t: "usage", ...engine.stats(), model: engine.model, sessionId: engine.sessionId, fallback: engine.fallback.active });
                 }
                 break;
             }
@@ -186,10 +289,8 @@ export async function serveDesktop(root, resumeId) {
                 pending.delete(m.id);
                 break;
             case "config": {
-                if (typeof m.model === "string" && m.model)
-                    engine.setModel(MODEL_ALIASES[m.model] ?? m.model);
-                else if (m.model === "")
-                    engine.setModel(engine.kind === "api" ? DEFAULT_MODEL : "");
+                if (typeof m.model === "string")
+                    engine.setModel(m.model ? MODEL_ALIASES[m.model] ?? m.model : ""); // vazio = modelo/perfil salvo
                 if (m.effort !== undefined)
                     engine.effort = isEffort(m.effort) ? m.effort : "";
                 if (["manual", "auto", "plan", "bypass"].includes(m.mode))

package/dist/engine.js

@@ -0,0 +1,79 @@
+import { MODEL_ALIASES, loadProfiles } from "./model.js";
+import { missingKeyMessage } from "./provider/openai-compat.js";
+import { resolveModel } from "./provider/resolve.js";
+/** O fallback é sempre este perfil de `providers` (não configurável). */
+export const FALLBACK_PROFILE = "qwen";
+/**
+ * Pronto só se o perfil existe, é válido, tem a chave no ambiente e o principal não é ele mesmo. Relê o config a
+ * cada chamada, como os perfis.
+ */
+export function fallbackStatus(primary, env) {
+    const { profiles, errors, rejected } = loadProfiles();
+    const p = profiles[FALLBACK_PROFILE];
+    const label = p?.label;
+    if (primary.trim().toLowerCase() === FALLBACK_PROFILE)
+        return { ready: false, reason: "o modelo principal já é o qwen", label };
+    if (rejected.includes(FALLBACK_PROFILE)) {
+        const why = errors.find((e) => e.toLowerCase().includes(`"${FALLBACK_PROFILE}"`)) ?? "";
+        return { ready: false, reason: `o perfil "${FALLBACK_PROFILE}" em ~/.brito/config.json está inválido (${why})` };
+    }
+    if (!p)
+        return { ready: false, reason: `sem perfil "${FALLBACK_PROFILE}" em providers no ~/.brito/config.json` };
+    if (!env[p.apiKeyEnv]?.trim())
+        return { ready: false, reason: missingKeyMessage(p), label };
+    return { ready: true, name: FALLBACK_PROFILE, label: p.label };
+}
+/** Modelo padrão do subagente `explore` no Claude: rápido e barato. */
+export const EXPLORE_DEFAULT = MODEL_ALIASES.haiku;
+/**
+ * Qual motor atende o modelo: perfil de endpoint → loop próprio (modo API), sem olhar a Anthropic nem o claude CLI.
+ * Claude → a regra de sempre: com ANTHROPIC_API_KEY, API direta; sem ela, o `claude` oficial (assinatura).
+ */
+export function pickEngine(model, env, hasCli) {
+    const r = resolveModel(model);
+    const name = model.trim().toLowerCase();
+    if (r.kind === "anthropic" && loadProfiles().rejected.includes(name)) {
+        const why = loadProfiles().errors.find((e) => e.toLowerCase().includes(`"${name}"`)) ?? "";
+        return { kind: "error", message: `o perfil "${name}" em ~/.brito/config.json está inválido (${why}); corrija antes de usar` };
+    }
+    if (r.kind === "openai")
+        return env[r.profile.apiKeyEnv]?.trim() ? { kind: "api" } : { kind: "error", message: missingKeyMessage(r.profile) };
+    if (env.ANTHROPIC_API_KEY)
+        return { kind: "api" };
+    if (hasCli())
+        return { kind: "claude" };
+    return { kind: "error", message: "Defina ANTHROPIC_API_KEY ou instale o Claude Code e rode `claude` → /login." };
+}
+/** Motivo do fallback quando a sessão já abre no qwen. */
+export const NO_ANTHROPIC = "sem conta da Anthropic";
+/**
+ * Motor da abertura: o de `pickEngine`, salvo quando um Claude não tem conta (sem ANTHROPIC_API_KEY e sem o `claude`)
+ * e o fallback está pronto — aí abre direto no qwen. Sem fallback pronto, o erro de sempre leva o motivo dele.
+ * Perfil inválido nunca vira fallback: continua o erro de perfil.
+ */
+export function openEngine(model, env, hasCli) {
+    const e = pickEngine(model, env, hasCli);
+    if (e.kind !== "error" || resolveModel(model).kind !== "anthropic" || loadProfiles().rejected.includes(model.trim().toLowerCase()))
+        return e;
+    const s = fallbackStatus(model, env);
+    return s.ready ? { kind: "fallback", label: s.label } : { kind: "error", message: `${e.message}\nFallback (qwen) indisponível: ${s.reason}.` };
+}
+/**
+ * Modelo de um subagente. BRITO_EXPLORE_MODEL manda no `explore`. Com o agente principal num endpoint, subagente
+ * que pediria um Claude fica no modelo do principal (senão a conta da Anthropic voltaria a ser usada em silêncio).
+ */
+export function subagentModel(def, parent, env) {
+    if (def.name === "explore" && env.BRITO_EXPLORE_MODEL)
+        return env.BRITO_EXPLORE_MODEL;
+    const wanted = def.model ?? (def.name === "explore" ? EXPLORE_DEFAULT : undefined);
+    if (resolveModel(parent).kind === "openai" && (!wanted || resolveModel(wanted).kind === "anthropic"))
+        return parent;
+    return wanted ?? parent;
+}
+/** Modelo da reflexão/consolidação de skills: BRITO_LEARN_MODEL, salvo se ele levaria a conta à Anthropic com um perfil ativo. */
+export function learnerModel(live, env) {
+    const wanted = env.BRITO_LEARN_MODEL;
+    if (!wanted)
+        return live;
+    return resolveModel(live).kind === "openai" && resolveModel(wanted).kind === "anthropic" ? live : wanted;
+}

package/dist/graph/store.js

@@ -209,3 +209,18 @@ export class GraphStore {
         await this.release();
     }
 }
+/**
+ * Abre o grafo no processo do Brito depois de um turno do claude: o servidor MCP dele solta o lock ao morrer, mas pode
+ * levar um instante além do `close` do filho. Uma tentativa extra curta cobre isso.
+ */
+export async function openGraphAfterClaude(root) {
+    try {
+        return await GraphStore.open(root);
+    }
+    catch (e) {
+        if (!(e instanceof GraphLockedError))
+            throw e;
+        await sleep(500);
+        return GraphStore.open(root);
+    }
+}

package/dist/model.js

@@ -132,5 +132,51 @@ export function parseModelArgs(raw) {
     const scope = flags.has("once") ? "once" : flags.has("global") && !flags.has("session") ? "global" : "session";
     return { model: model ? resolveModelAlias(model) : "", scope, errors };
 }
-/** Texto de ajuda mostrado por `/model` sem argumentos. */
-export const MODEL_HELP = "uso: /model <nome|alias> [--global|--session|--once]  (aliases: " + Object.keys(MODEL_ALIASES).join(", ") + ")";
+/** Texto de ajuda mostrado por `/model` sem argumentos (perfis de endpoint entram junto dos aliases). */
+export function modelHelp() {
+    const profiles = Object.keys(loadProfiles().profiles);
+    return "uso: /model <nome|alias> [--global|--session|--once]  (aliases: " + Object.keys(MODEL_ALIASES).join(", ") + ")" +
+        (profiles.length ? `  (endpoints: ${profiles.join(", ")})` : "");
+}
+const isText = (v) => typeof v === "string" && v.trim() !== "";
+/**
+ * Perfis de endpoint compatível com OpenAI (`providers` no config). Relido a cada chamada: é barato e o config muda
+ * durante a sessão. Perfil inválido não derruba o Brito: fica de fora e o motivo vai em `errors`.
+ */
+export function loadProfiles() {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(configPath(), "utf8"))?.providers;
+    }
+    catch {
+        return { profiles: {}, errors: [], rejected: [] };
+    }
+    const profiles = {};
+    const errors = [];
+    /** nomes de perfis inválidos: escolher um deles é erro, nunca cair no Claude */
+    const rejected = [];
+    if (!raw || typeof raw !== "object")
+        return { profiles, errors, rejected };
+    for (const [key, v] of Object.entries(raw)) {
+        const name = key.trim().toLowerCase();
+        const missing = ["baseURL", "model", "apiKeyEnv"].filter((f) => !isText(v?.[f]));
+        if (v?.type !== "openai") {
+            errors.push(`perfil "${key}" ignorado: type precisa ser "openai"`);
+            rejected.push(name);
+            continue;
+        }
+        if (missing.length) {
+            errors.push(`perfil "${key}" ignorado: faltam ${missing.join(", ")}`);
+            rejected.push(name);
+            continue;
+        }
+        profiles[name] = {
+            name, type: "openai", label: isText(v.label) ? v.label.trim() : name,
+            baseURL: v.baseURL.trim(), model: v.model.trim(), apiKeyEnv: v.apiKeyEnv.trim(),
+            contextWindow: Number(v.contextWindow) > 0 ? Number(v.contextWindow) : 128_000,
+            vision: v.vision === true,
+            thinkingToggle: v.thinkingToggle === true,
+        };
+    }
+    return { profiles, errors, rejected };
+}

package/dist/provider/anthropic.js

@@ -0,0 +1,31 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { resolveModel } from "./resolve.js";
+/** API da Anthropic, exatamente como o Brito sempre chamou (system em cache, streaming quando há quem leia o texto). */
+export class AnthropicProvider {
+    kind = "anthropic";
+    client = new Anthropic();
+    async send(req, hooks = {}) {
+        const params = {
+            model: resolveModel(req.model).wireModel, // aliases (sonnet, opus…) viram o id real
+            max_tokens: req.maxTokens,
+            system: [{ type: "text", text: req.system, cache_control: { type: "ephemeral" } }],
+            ...(req.tools?.length ? { tools: req.tools } : {}),
+            messages: req.messages,
+        };
+        let msg;
+        if (hooks.onText) {
+            const stream = this.client.messages.stream(params, { signal: hooks.signal });
+            stream.on("text", (t) => hooks.onText(t));
+            msg = await stream.finalMessage();
+        }
+        else
+            msg = await this.client.messages.create(params, { signal: hooks.signal });
+        const u = msg.usage;
+        const content = msg.content.flatMap((b) => b.type === "text" ? [{ type: "text", text: b.text }] : b.type === "tool_use" ? [{ type: "tool_use", id: b.id, name: b.name, input: b.input }] : []);
+        const stopReason = msg.stop_reason === "end_turn" || msg.stop_reason === "tool_use" || msg.stop_reason === "max_tokens" ? msg.stop_reason : "other";
+        return {
+            content, stopReason,
+            usage: { input: u.input_tokens + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0), output: u.output_tokens, cacheRead: u.cache_read_input_tokens ?? 0 },
+        };
+    }
+}

package/dist/provider/fallback.js

@@ -0,0 +1,147 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { FALLBACK_PROFILE } from "../engine.js";
+export const triggersFallback = (k) => k !== "other";
+/**
+ * Classifica um erro da API da Anthropic (já depois dos retries do SDK). Na dúvida, `other`: melhor não trocar do que
+ * esconder um bug atrás do qwen.
+ */
+export function classifyAnthropicError(e) {
+    if (e instanceof Anthropic.APIUserAbortError || e?.name === "AbortError")
+        return "other";
+    if (e instanceof Anthropic.APIConnectionError)
+        return "network"; // inclui APIConnectionTimeoutError
+    if (!(e instanceof Anthropic.APIError))
+        return "other";
+    const status = e.status ?? 0;
+    const type = e.type ?? "";
+    if (status === 429 || type === "rate_limit_error")
+        return "rate_limit";
+    if (status === 402 || type === "billing_error" || (status === 400 && /credit balance is too low/i.test(e.message)))
+        return "quota";
+    if (status === 401 || status === 403 || type === "authentication_error" || type === "permission_error")
+        return "auth";
+    if (type === "timeout_error")
+        return "network";
+    if (status === 529 || status >= 500 || type === "overloaded_error")
+        return "overloaded";
+    return "other";
+}
+/** Acumula os sinais de falha de um evento do stream-json. Só a thread principal: subagente que falha não derruba o turno. */
+export function collectClaudeFailure(f, ev) {
+    if (ev?.parent_tool_use_id)
+        return;
+    if (ev?.type === "assistant" && typeof ev.error === "string") {
+        f.error = ev.error;
+        if (typeof ev.api_error_status === "number")
+            f.status = ev.api_error_status;
+    }
+    else if (ev?.type === "result" && ev.is_error) {
+        f.result = String(ev.result ?? "");
+        if (typeof ev.api_error_status === "number")
+            f.status = ev.api_error_status;
+    }
+}
+const CLI_AUTH_ERRORS = new Set(["authentication_failed", "oauth_org_not_allowed", "account_on_hold", "verification_required", "cloud_credential_error"]);
+/** Erros do CLI que são de conteúdo/bug: não troca, mesmo que o texto fale em "limit". */
+const CLI_OTHER_ERRORS = new Set(["invalid_request", "model_not_found", "max_output_tokens"]);
+/** "limit reached" que não é de conta: contexto, orçamento de agentes, concorrência. */
+const NOT_ACCOUNT_LIMIT = /context limit|budget limit|subagent limit|turn budget|export limit|device limit/i;
+const SUBSCRIPTION_LIMIT = /usage limit reached|limit reached|hit your (?:\w+ )?limit|resets \d|out of usage credits|spend limit|credit balance/i;
+/**
+ * Classifica a falha de um turno do `claude` CLI: primeiro pelos campos estruturados do stream-json, depois pelo texto
+ * (as frases mudam entre versões). Na dúvida, `other`. Interrupção nunca chega aqui (a sessão filtra antes).
+ */
+export function classifyClaudeCliFailure(f) {
+    if (f.spawnError)
+        return /ENOENT|EACCES|not found/i.test(f.spawnError) ? "auth" : "other";
+    const text = `${f.result ?? ""}\n${f.stderr}`;
+    const accountLimit = SUBSCRIPTION_LIMIT.test(text) && !NOT_ACCOUNT_LIMIT.test(text);
+    const e = f.error ?? "";
+    if (CLI_OTHER_ERRORS.has(e))
+        return "other";
+    if (CLI_AUTH_ERRORS.has(e))
+        return "auth";
+    if (e === "billing_error")
+        return "quota";
+    if (e === "rate_limit")
+        return accountLimit ? "quota" : "rate_limit";
+    if (e === "overloaded" || e === "server_error")
+        return "overloaded";
+    const s = f.status ?? 0;
+    if (s === 429)
+        return accountLimit ? "quota" : "rate_limit";
+    if (s === 402)
+        return "quota";
+    if (s === 401 || s === 403)
+        return "auth";
+    if (s === 529 || s >= 500)
+        return "overloaded";
+    if (NOT_ACCOUNT_LIMIT.test(text))
+        return "other";
+    if (accountLimit)
+        return "quota";
+    if (/rate.?limit/i.test(text))
+        return "rate_limit";
+    if (/invalid api key|\/login|not logged in|oauth token|failed to authenticate|log in again/i.test(text))
+        return "auth";
+    if (/overloaded|\b529\b/i.test(text))
+        return "overloaded";
+    return "other";
+}
+/** Primeira linha do erro, curta, para o aviso e o `/fallback`. */
+export const shortError = (e, max = 120) => {
+    const line = String(e?.message ?? e).split("\n")[0].trim();
+    return line.length > max ? line.slice(0, max - 1) + "…" : line;
+};
+export const newFallbackState = (primary) => ({ primary, active: false });
+/** `/model <x>` é escolha explícita: vira o principal e desfaz o fallback (inclusive `/model qwen`). */
+export function chooseModel(s, model) {
+    s.primary = model;
+    s.active = false;
+    s.reason = undefined;
+    s.at = undefined;
+}
+/** A troca automática aconteceu. */
+export function activateFallback(s, reason, at = Date.now()) {
+    s.active = true;
+    s.reason = reason;
+    s.at = at;
+}
+/** Aviso impresso na troca (modo API e claude CLI): a troca nunca é silenciosa. */
+export const fallbackWarning = (kind, why, label) => `⚠ Claude falhou (${kind}: ${why}) — seguindo com ${label}. /fallback para detalhes, /model <claude> para voltar.`;
+/**
+ * O turno do claude CLI que falhou deve ser refeito no qwen? Só com falha de conta/capacidade, fallback pronto e
+ * ainda não usado na sessão. Interrupção não deixa `failure` (a sessão filtra), mas o `aborted` fica de garantia.
+ */
+export function cliShouldFallBack(failure, state, status, aborted = false) {
+    return !!failure && triggersFallback(failure.kind) && status.ready && !state.active && !aborted;
+}
+/** Nota que precede o pedido refeito no qwen depois da troca de motor (spec §5.5). */
+export const RETRY_NOTE = "[O modelo anterior (Claude) falhou no meio deste pedido. O que já foi feito está no histórico acima; continue de onde parou sem refazer ações já concluídas.]";
+/** Sessão retomada (app reaberto): o que veio antes da reabertura ficou no claude CLI e não está no histórico. */
+export const RESUMED_NOTE = "[A conversa anterior à reabertura da sessão não foi herdada: só o que veio depois dela está no histórico. Se faltar contexto, pergunte ao usuário em vez de supor.]";
+export const retryPrompt = (text, resumed = false) => `${RETRY_NOTE}${resumed ? `\n${RESUMED_NOTE}` : ""}\n\n${text}`;
+/**
+ * Modelo a devolver depois de um turno com `/model --once`. O `--once` zera o fallback, então `active` no fim do turno
+ * quer dizer que a troca aconteceu durante ele: aí o `restore` é descartado (voltaria ao Claude que acabou de cair).
+ */
+export const onceRestore = (restore, fallbackActive) => (fallbackActive ? null : restore);
+const hhmm = (ms) => { const d = new Date(ms); return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`; };
+/**
+ * Linhas do `/fallback`. Principal = o modelo vivo, salvo com o fallback ativo (aí é o principal original e o qwen
+ * aparece em uso). `status` vem de `fallbackStatus(state.primary, env)`; `engineLabel` é o motor do principal.
+ */
+export function renderFallback(state, liveModel, engineLabel, status) {
+    const primary = state.active ? state.primary : liveModel;
+    const name = status.label ?? "—";
+    const self = !state.active && primary.trim().toLowerCase() === FALLBACK_PROFILE;
+    const fb = state.active ? `${name}  qwen · ~/.brito/config.json  ● em uso`
+        : status.ready ? `${name}  qwen · ~/.brito/config.json  ✓ pronto`
+            : self ? `${name}  — o modelo principal já é o qwen`
+                : `${name}  ✗ ${status.reason}`;
+    const estado = state.active ? `ATIVO desde ${hhmm(state.at ?? Date.now())} — Claude falhou: ${state.reason ?? "?"}. /model <claude> para voltar`
+        : status.ready ? "inativo — troca automática se o Claude falhar por limite, crédito, auth ou sobrecarga"
+            : self ? "não se aplica"
+                : "indisponível — sem troca automática nesta sessão";
+    return [`  principal  ${primary}  (${engineLabel})`, `  fallback   ${fb}`, `  estado     ${estado}`];
+}

package/dist/provider/index.js

@@ -0,0 +1,27 @@
+import { AnthropicProvider } from "./anthropic.js";
+import { OpenAICompatProvider } from "./openai-compat.js";
+import { resolveModel } from "./resolve.js";
+let factory = null;
+/** Só para testes: troca a criação de provedores. `null` volta ao normal. */
+export function setProviderFactory(f) { factory = f; }
+let anthropic;
+const openai = new Map();
+/**
+ * Provedor de um modelo pelo nome que o usuário usa. O cliente da Anthropic só nasce quando um modelo Claude é usado:
+ * com um perfil de endpoint escolhido, nada da Anthropic é instanciado.
+ */
+export function providerFor(name) {
+    const r = resolveModel(name);
+    if (factory)
+        return factory(r);
+    if (r.kind === "anthropic")
+        return (anthropic ??= new AnthropicProvider());
+    // O config pode mudar na sessão: refaz o provedor quando o perfil muda.
+    const key = JSON.stringify(r.profile);
+    const hit = openai.get(r.name);
+    if (hit?.key === key)
+        return hit.provider;
+    const provider = new OpenAICompatProvider(r.profile);
+    openai.set(r.name, { key, provider });
+    return provider;
+}