brito-cli 0.6.4 → 0.7.0

package/README.md

@@ -147,6 +147,7 @@ OK: 20 arquivos, 66 símbolos, 54 chamadas, 17 imports | +0 ~0 -0 =20 (28ms)
 |---|---|
 | `/help` | list commands |
 | `/model`, `/effort`, `/reasoning` | choose model, reasoning effort and thinking (session, global or once) |
+| `/fallback` | shows the main model and the fallback (qwen), and whether the switch already happened |
 | `/modo` or `Shift+Tab` | switch permission mode: manual → auto-edits → plan → bypass ("everything allowed") |
 | `/skills` | list skills · `pending` · `approve <name>` · `reject <name>` · `consolidate` · `rm <name>` · `promote <name>` |
 | `/learn` | extract skills from the last turn now |
@@ -178,6 +179,47 @@ Brito has **no database drivers and connects to nothing on its own**. When it ne
 - Prefer read-only roles and non-production environments when you give an agent database access.
 - A proposed skill that contains a destructive command is highlighted at review time, so you decide whether it needs a guard (backup, copy, confirmation).
 
+## OpenAI-compatible endpoint (e.g. Qwen on OCI)
+
+> Full step-by-step (install, key, profile, and how to give people access to the repository, in Portuguese): [docs/GUIA-QWEN.md](docs/GUIA-QWEN.md).
+
+Besides Claude, Brito runs on any model served through the OpenAI **Chat Completions** API (vLLM, OCI Generative AI, LiteLLM, Ollama…) with tool calling. Add a profile to `~/.brito/config.json`:
+
+```json
+{
+  "providers": {
+    "qwen": {
+      "type": "openai",
+      "label": "Qwen 27B (OCI)",
+      "baseURL": "https://inference.generativeai.<region>.oci.oraclecloud.com/openai/v1",
+      "model": "<model id; on OCI, the dedicated endpoint OCID>",
+      "apiKeyEnv": "BRITO_QWEN_API_KEY",
+      "contextWindow": 262144,
+      "vision": false,
+      "thinkingToggle": true
+    }
+  }
+}
+```
+
+The key is **not** stored in the config: put it in the environment variable named by `apiKeyEnv`. Then:
+
+```bash
+brito --model qwen            # this session
+/model qwen --global          # inside the REPL: make it the default
+```
+
+With a profile selected, **everything** goes to the endpoint: main agent, subagents (`explore` stops using Haiku), context summaries and skill learning; Brito starts without `ANTHROPIC_API_KEY` and without the `claude` CLI. `/reasoning none` turns the model's reasoning off (much faster answers on Qwen). `thinkingToggle: true` only for servers that accept `chat_template_kwargs` (vLLM/Qwen); without it `/reasoning none` has no effect, but no unknown parameter is sent. Images are only sent with `"vision": true`. Deliberate exception: `BRITO_EXPLORE_MODEL` still decides the `explore` subagent; a `BRITO_LEARN_MODEL` pointing at Claude is ignored while a profile is active. A broken profile in the config never falls back to Claude: Brito warns and stops. `/effort` stays exclusive to `claude` CLI mode, and a profile does not run inside the `claude` CLI (`/model` tells you to reopen with `--model`).
+
+### Fallback to Qwen
+
+With Claude as the main model (API or `claude` CLI), the `qwen` profile is the automatic fallback — always that one, no new config key. If Claude fails because of a **subscription limit, rate limit, credit, authentication, overload or network** error, Brito warns and redoes the request on Qwen with the conversation so far (tools that already ran stay in the history, so they are not repeated). In `claude` CLI mode the whole engine switches to Brito's own loop.
+
+- The switch happens once per session and never reverts on its own: `/model <claude>` goes back to Claude (and the fallback can trigger again later).
+- It does not switch on Ctrl+C or on content errors (invalid request, `max_tokens`, broken tool).
+- Without `ANTHROPIC_API_KEY` and without the `claude` CLI, Brito opens straight on Qwen, with a warning. If the fallback is not ready, the usual error includes why (e.g. `BRITO_QWEN_API_KEY` is missing). An invalid `qwen` profile is still an error, never a silent fallback.
+- `/fallback` shows the state. In the desktop app, send `/fallback` as a message; the status bar shows Qwen while the fallback is active.
+
 ## Configuration
 
 `BRITO_MODEL`, `BRITO_EFFORT`, `BRITO_EXPLORE_MODEL`, `BRITO_LEARN_MODEL`, `BRITO_HOME` (where global skills and history live), `BRITO_CONFIG`, `BRITO_COLOR`, `BRITO_BANNER` (`compact` or `full`; default: full screen on windows of 95+ columns and 28+ rows), `BRITO_INDEX_IGNORED`, `BRITO_SKILL_MIN_TOOLS` (how long a turn must be to trigger reflection when nothing else does), `BRITO_SKILLS` (`auto` default, `ask`, `off`), `BRITO_SHELL` (shell used by the `bash` tool; on Windows defaults to Git Bash when installed).

package/README.pt-BR.md

@@ -143,6 +143,7 @@ OK: 20 arquivos, 66 símbolos, 54 chamadas, 17 imports | +0 ~0 -0 =20 (28ms)
 |---|---|
 | `/help` | lista os comandos |
 | `/model`, `/effort`, `/reasoning` | escolhem modelo, esforço de raciocínio e thinking (sessão, global ou uma vez) |
+| `/fallback` | mostra o modelo principal e o fallback (qwen), e se a troca já aconteceu |
 | `/modo` ou `Shift+Tab` | troca o modo de permissão: manual → auto-edições → plano → tudo liberado |
 | `/skills` | lista skills · `pending` · `approve <nome>` · `reject <nome>` · `consolidate` · `rm <nome>` · `promote <nome>` |
 | `/learn` | extrai skills do último turno agora |
@@ -174,6 +175,54 @@ O Brito **não tem drivers de banco e não se conecta a nada sozinho**. Quando p
 - Prefira papéis somente leitura e ambientes que não sejam de produção ao dar acesso a banco para um agente.
 - Uma skill proposta que contém comando destrutivo é destacada na revisão, para você decidir se precisa de uma guarda (backup, cópia, confirmação).
 
+## Endpoint compatível com OpenAI (ex.: Qwen no OCI)
+
+> Passo a passo completo (instalação, chave, perfil e como dar acesso ao repositório): [docs/GUIA-QWEN.md](docs/GUIA-QWEN.md).
+
+Além do Claude, o Brito roda com qualquer modelo servido pela API **Chat Completions** da OpenAI (vLLM, OCI Generative AI, LiteLLM, Ollama…) com chamada de ferramentas. Cadastre um perfil em `~/.brito/config.json`:
+
+```json
+{
+  "providers": {
+    "qwen": {
+      "type": "openai",
+      "label": "Qwen 27B (OCI)",
+      "baseURL": "https://inference.generativeai.<região>.oci.oraclecloud.com/openai/v1",
+      "model": "<id do modelo; no OCI, o OCID do endpoint dedicado>",
+      "apiKeyEnv": "BRITO_QWEN_API_KEY",
+      "contextWindow": 262144,
+      "vision": false,
+      "thinkingToggle": true
+    }
+  }
+}
+```
+
+A chave **não** fica no config: ponha na variável de ambiente indicada em `apiKeyEnv`. Depois:
+
+```bash
+brito --model qwen            # esta sessão
+/model qwen --global          # dentro do REPL: vira o padrão
+```
+
+Com um perfil escolhido, **tudo** vai para o endpoint: agente principal, subagentes (o `explore` deixa de usar o Haiku), resumo de contexto e aprendizado de skills; o Brito abre sem `ANTHROPIC_API_KEY` e sem o `claude` CLI. `/reasoning none` desliga o raciocínio do modelo (respostas bem mais rápidas no Qwen). `thinkingToggle: true` só para servidores que aceitam `chat_template_kwargs` (vLLM/Qwen); sem ele o `/reasoning none` não tem efeito, mas nenhum parâmetro estranho é enviado. Imagens só são enviadas com `"vision": true`. Exceção consciente: `BRITO_EXPLORE_MODEL` continua mandando no subagente `explore`; já um `BRITO_LEARN_MODEL` que aponte para um Claude é ignorado enquanto um perfil estiver ativo. Perfil com erro no config não cai no Claude: o Brito avisa e para. `/effort` continua exclusivo do modo `claude` CLI, e um perfil não roda dentro do `claude` CLI (o `/model` avisa para reabrir com `--model`).
+
+### Fallback para o Qwen
+
+Com o Claude como modelo principal (API ou `claude` CLI), o perfil `qwen` é o fallback automático — sempre ele, sem chave nova no config. Se o Claude falha por **limite da assinatura, rate limit, crédito, autenticação, sobrecarga ou rede**, o Brito avisa e refaz o pedido no Qwen com a conversa até ali (as tools que já rodaram ficam no histórico, para não serem repetidas). No modo `claude` CLI o motor inteiro troca para o loop próprio do Brito.
+
+- A troca acontece uma vez por sessão e não volta sozinha: `/model <claude>` volta ao Claude (e o fallback pode disparar de novo depois).
+- Não troca por Ctrl+C nem por erro de conteúdo (requisição inválida, `max_tokens`, tool quebrada).
+- Sem `ANTHROPIC_API_KEY` e sem o `claude` CLI, o Brito já abre no Qwen, com aviso. Sem o fallback pronto, o erro de sempre inclui o motivo (ex.: falta `BRITO_QWEN_API_KEY`). Perfil `qwen` inválido continua sendo erro, nunca fallback silencioso.
+- `/fallback` mostra o estado. No app de desktop, envie `/fallback` como mensagem; a barra de status mostra o Qwen quando o fallback está ativo.
+
+```
+/fallback
+  principal  claude-opus-5-5  (claude CLI · assinatura)
+  fallback   Qwen 27B (OCI)  qwen · ~/.brito/config.json  ✓ pronto
+  estado     inativo — troca automática se o Claude falhar por limite, crédito, auth ou sobrecarga
+```
+
 ## Configuração
 
 `BRITO_MODEL`, `BRITO_EFFORT`, `BRITO_EXPLORE_MODEL`, `BRITO_LEARN_MODEL`, `BRITO_HOME` (onde ficam skills globais e histórico), `BRITO_CONFIG`, `BRITO_COLOR`, `BRITO_BANNER` (`compact` ou `full`; padrão: tela cheia em janelas de 95+ colunas e 28+ linhas), `BRITO_INDEX_IGNORED`, `BRITO_SKILL_MIN_TOOLS` (tamanho mínimo do turno para disparar a reflexão quando nada mais dispara), `BRITO_SKILLS` (`auto` padrão, `ask`, `off`), `BRITO_SHELL` (shell da tool `bash`; no Windows usa o Git Bash se instalado).

package/dist/agent/agents.js

@@ -8,7 +8,7 @@ const BUILTIN = [
         name: "explore",
         description: "Somente leitura e rápido. Localiza código, mapeia fluxos e responde 'onde/como/quem chama' usando o grafo. Não edita nada.",
         tools: READ_TOOLS,
-        model: process.env.BRITO_EXPLORE_MODEL ?? "claude-haiku-4-5-20251001",
+        // Sem modelo fixo: subagentModel (engine.ts) escolhe Haiku no Claude, o modelo principal num endpoint, ou BRITO_EXPLORE_MODEL.
         prompt: "Você é um agente de exploração de código. Descubra o que foi pedido com o mínimo de leitura: comece pelo grafo (graph_search/graph_context/graph_callers/graph_callees), leia só os trechos apontados. Entregue achados com caminhos `arquivo:linha`, sem despejar código longo.",
         source: "builtin",
     },

package/dist/agent/claude-cli.js

@@ -7,9 +7,11 @@ import { skillsIndex } from "../skills/store.js";
 import { MCP_NAME, MCP_PREFIX, APPROVE_TOOL } from "../mcp/server.js";
 import { ui as terminalUi } from "../ui/ui.js";
 import { MODE_ENV, perms } from "../permissions.js";
-import { wireEffort } from "../model.js";
+import { DEFAULT_MODEL, wireEffort } from "../model.js";
+import { subagentModel } from "../engine.js";
 import { claudeCommand } from "../util/platform.js";
 import { fmtBytes, findImages, splitOversize } from "../util/images.js";
+import { classifyClaudeCliFailure, collectClaudeFailure, shortError } from "../provider/fallback.js";
 // Backend alternativo: delega ao `claude` oficial, que autentica com o /login do usuário.
 // O brito nunca lê nem envia o token da assinatura. Grafo, memória e skills chegam ao claude via MCP.
 export function hasClaudeCli() {
@@ -21,6 +23,89 @@ const resultText = (c) => (typeof c === "string" ? c : Array.isArray(c) ? c.map(
 /** Nome das tools do Brito → nome que o claude enxerga. */
 const CLAUDE_TOOL = { read_file: "Read", glob: "Glob", grep: "Grep", write_file: "Write", edit_file: "Edit", bash: "Bash" };
 const claudeToolName = (n) => CLAUDE_TOOL[n] ?? MCP_PREFIX + n;
+/** Nome nativo do claude → tool do Brito (inverso de CLAUDE_TOOL); os MCP já chegam sem o prefixo. */
+const BRITO_TOOL = Object.fromEntries(Object.entries(CLAUDE_TOOL).map(([b, c]) => [c, b]));
+export const ORPHAN_RESULT = "o modelo anterior caiu antes do resultado";
+const blocks = (c) => (typeof c === "string" ? (c ? [{ type: "text", text: c }] : []) : [...c]);
+/** tool_use com o nome e os parâmetros do Brito (Read/Write/Edit usam `file_path`; o Brito usa `path`). */
+function britoToolUse(b) {
+    const name = BRITO_TOOL[b.name] ?? b.name;
+    let input = b.input;
+    if (name !== b.name && input && typeof input === "object" && "file_path" in input && !("path" in input)) {
+        const { file_path, ...rest } = input;
+        input = { path: file_path, ...rest };
+    }
+    return { ...b, name, input };
+}
+/**
+ * Histórico do claude CLI (todos os TurnRecord da sessão) → `Msg[]` válido para o loop próprio, na troca para o qwen.
+ * O stream-json manda um evento por bloco, então mensagens seguidas do mesmo papel viram uma; `tool_use` sem
+ * `tool_result` (o turno que caiu) ganha um resultado de erro. Não altera os TurnRecord (a reflexão ainda os usa).
+ */
+export function turnsToMessages(turns) {
+    const out = [];
+    for (const m of turns.flatMap((t) => t.messages)) {
+        const content = blocks(m.content).map((b) => (b.type === "tool_use" ? britoToolUse(b) : b));
+        if (!content.length)
+            continue;
+        const last = out.at(-1);
+        if (last?.role === m.role)
+            last.content.push(...content);
+        else
+            out.push({ role: m.role, content });
+    }
+    for (let i = 0; i < out.length; i++) {
+        if (out[i].role !== "assistant")
+            continue;
+        const next = out[i + 1]?.role === "user" ? out[i + 1] : null;
+        const answered = new Set(next?.content.flatMap((b) => (b.type === "tool_result" ? [b.tool_use_id] : [])));
+        const missing = out[i].content.flatMap((b) => (b.type === "tool_use" && !answered.has(b.id)
+            ? [{ type: "tool_result", tool_use_id: b.id, content: ORPHAN_RESULT, is_error: true }] : []));
+        if (!missing.length)
+            continue;
+        if (next)
+            next.content.unshift(...missing);
+        else
+            out.splice(i + 1, 0, { role: "user", content: missing });
+    }
+    return out;
+}
+/**
+ * Histórico que o qwen herda na troca: todos os turnos, menos o pedido do turno que caiu quando ele não chegou a
+ * produzir nada (o pedido volta logo em seguida, com a nota de `retryPrompt`, e ficaria duplicado).
+ */
+export function historyForFallback(turns) {
+    const failed = turns.at(-1);
+    return turnsToMessages(failed && failed.messages.length <= 1 ? turns.slice(0, -1) : turns);
+}
+const HANDOFF_BUDGET = 60_000;
+const clip = (s, n) => (s.length > n ? s.slice(0, n) + `… [+${s.length - n} caracteres]` : s);
+/**
+ * Turnos feitos no modo API → texto que abre o próximo prompt do claude CLI na volta. O claude retoma a própria sessão
+ * (--resume) e não viu nada disso; com o texto no prompt, ele fica gravado na sessão dele e vale para os turnos seguintes.
+ * Passando de `budget`, os turnos mais antigos saem primeiro.
+ */
+export function handoffNote(turns, label, budget = HANDOFF_BUDGET) {
+    const rendered = turns.map((t) => t.messages.flatMap((m) => blocks(m.content).flatMap((b) => {
+        if (b.type === "text" && b.text)
+            return [`${m.role === "user" ? "USUÁRIO" : "AGENTE"}: ${clip(b.text, 4_000)}`];
+        if (b.type === "tool_use")
+            return [`→ ${b.name}(${clip(JSON.stringify(b.input), 600)})`];
+        if (b.type === "tool_result")
+            return [`← ${b.is_error ? "[ERRO] " : ""}${clip(resultText(b.content), b.is_error ? 1_500 : 1_000)}`];
+        return [];
+    })).join("\n")).filter(Boolean);
+    if (!rendered.length)
+        return "";
+    let total = rendered.reduce((n, t) => n + t.length + 2, 0), dropped = 0;
+    while (rendered.length > 1 && total > budget) {
+        total -= rendered.shift().length + 2;
+        dropped++;
+    }
+    return `[Contexto: enquanto você esteve fora, a conversa seguiu no ${label} (modo API do Brito). É isto que aconteceu lá, em ordem; ` +
+        `as edições e comandos já estão no disco. Continue a partir daqui.${dropped ? ` (${dropped} turno(s) mais antigo(s) omitido(s))` : ""}]\n\n` +
+        `${rendered.join("\n\n")}\n\n[Fim do contexto. Pedido atual:]\n\n`;
+}
 /** Agentes do Brito viram subagentes do claude (--agents), no lugar do `delegate`. */
 function claudeAgents() {
     const out = {};
@@ -29,7 +114,7 @@ function claudeAgents() {
             description: a.description,
             prompt: a.prompt,
             ...(a.tools === "all" ? {} : { tools: a.tools.map(claudeToolName) }),
-            ...(a.model?.includes("haiku") ? { model: "haiku" } : {}),
+            ...(subagentModel(a, DEFAULT_MODEL, process.env).includes("haiku") ? { model: "haiku" } : {}),
         };
     }
     return out;
@@ -39,7 +124,8 @@ function claudeAgents() {
  * Só a thread principal entra: mensagens de subagentes (`parent_tool_use_id`) têm contexto próprio.
  */
 export function recordStreamEvent(turn, ev, loadedSkills) {
-    if (ev?.parent_tool_use_id)
+    // A mensagem sintética de erro ("5-hour limit reached"…) não é fala do modelo: o qwen a herdaria como resposta.
+    if (ev?.parent_tool_use_id || ev?.is_api_error_message)
         return;
     if (ev?.type === "assistant") {
         const rec = [];
@@ -92,6 +178,10 @@ export class ClaudeSession {
     /** transcript do último turno (thread principal), montado do stream-json para a reflexão de skills */
     lastTurn = null;
     recentTurns = [];
+    /** todos os turnos da sessão, sem corte: viram o histórico do qwen se o claude cair (`turnsToMessages`) */
+    allTurns = [];
+    /** por que o último turno falhou (null = deu certo ou foi interrompido); o fallback para o qwen decide por ele */
+    lastFailure = null;
     /** skills carregadas via skill_load (que roda no servidor MCP, outro processo) */
     loadedSkills = new Set();
     /** último turno em andamento, para o Ctrl+C */
@@ -102,7 +192,19 @@ export class ClaudeSession {
     get sessionId() { return this.id; }
     /** Retoma uma conversa do claude (--resume) em vez de começar outra. */
     resume(id) { this.id = id; this.started = true; }
-    reset() { this.id = randomUUID(); this.started = false; this.contextTokens = 0; this.recentTurns = []; }
+    reset() { this.id = randomUUID(); this.started = false; this.contextTokens = 0; this.recentTurns = []; this.allTurns = []; this.pendingHandoff = ""; }
+    /** contexto do modo API ainda não entregue ao claude: abre o próximo prompt (`handoffNote`) */
+    pendingHandoff = "";
+    /**
+     * Volta do modo API: os turnos feitos lá chegam ao claude no próximo prompt e entram em `allTurns`, para que uma
+     * nova queda para o qwen herde também o que foi feito nele.
+     */
+    handoff(turns, label) {
+        if (!turns.length)
+            return;
+        this.pendingHandoff += handoffNote(turns, label);
+        this.allTurns.push(...turns);
+    }
     abort() { if (!this.child)
         return; this.aborted = true; this.child.kill("SIGINT"); }
     /** No Windows `kill("SIGINT")` termina o processo sem sinal nem código 130: lembramos que fomos nós que interrompemos. */
@@ -148,21 +250,26 @@ export class ClaudeSession {
             if (imgs.length)
                 ui.info(`📎 ${imgs.map((i) => `${i.name} (${fmtBytes(i.bytes)})`).join(", ")} anexado${imgs.length > 1 ? "s" : ""}`);
             // O claude vê a imagem pela tool Read: o prompt diz quais arquivos são imagens anexadas pelo usuário.
-            const prompt = imgs.length ? `${text}\n\n[O usuário anexou ${imgs.length > 1 ? "estes arquivos" : "este arquivo"}; abra com a tool Read para vê-${imgs.length > 1 ? "las" : "la"}:\n${imgs.map((i) => `- ${i.path}`).join("\n")}]` : text;
-            const cmd = claudeCommand(this.args(prompt, [...new Set(imgs.map((i) => path.dirname(i.path)))]));
+            const prompt = this.pendingHandoff + (imgs.length ? `${text}\n\n[O usuário anexou ${imgs.length > 1 ? "estes arquivos" : "este arquivo"}; abra com a tool Read para vê-${imgs.length > 1 ? "las" : "la"}:\n${imgs.map((i) => `- ${i.path}`).join("\n")}]` : text);
+            const cmd = (this.o.command ?? claudeCommand)(this.args(prompt, [...new Set(imgs.map((i) => path.dirname(i.path)))]));
             const child = (this.child = spawn(cmd.command, cmd.args, {
                 cwd: this.o.root, stdio: ["ignore", "pipe", "pipe"],
                 // `/reasoning none`: o claude desliga o raciocínio com MAX_THINKING_TOKENS=0 (não há `--effort none`)
                 env: { ...process.env, ...this.o.env, BRITO_DEPTH: String(Number(process.env.BRITO_DEPTH ?? 0) + 1), ...(wireEffort(this.effort).thinking ? {} : { MAX_THINKING_TOKENS: "0" }) },
             }));
             let buf = "", stderr = "", ok = true, interrupted = false;
+            const failure = { stderr: "", code: null };
+            this.lastFailure = null;
             const names = new Map();
             const turn = { messages: [{ role: "user", content: text }], toolCalls: 0, errors: 0, finished: false };
             this.lastTurn = turn;
             this.recentTurns = [...this.recentTurns, turn].slice(-3);
+            this.allTurns.push(turn);
             const handle = (ev) => {
                 recordStreamEvent(turn, ev, this.loadedSkills);
-                if (ev.type === "assistant") {
+                collectClaudeFailure(failure, ev);
+                // A mensagem sintética de erro sai pelo `result` (ui.error); aqui viraria fala do Brito e modelo "<synthetic>".
+                if (ev.type === "assistant" && !ev.is_api_error_message) {
                     for (const b of ev.message?.content ?? []) {
                         if (b.type === "thinking" && b.thinking && !ev.parent_tool_use_id)
                             ui.thinking(b.thinking);
@@ -189,6 +296,10 @@ export class ClaudeSession {
                             ui.toolEnd(b.tool_use_id, !!b.is_error, resultText(b.content));
                 }
                 else if (ev.type === "result") {
+                    // Houve turno (mesmo com erro, ex.: limite da assinatura): o claude já gravou a sessão com este id, e o
+                    // próximo turno precisa de --resume — repetir --session-id dá "Session ID … is already in use".
+                    this.started = true;
+                    this.pendingHandoff = ""; // o prompt com o contexto já está gravado na sessão do claude
                     this.usage.input += (ev.usage?.input_tokens ?? 0) + (ev.usage?.cache_read_input_tokens ?? 0) + (ev.usage?.cache_creation_input_tokens ?? 0);
                     this.usage.output += ev.usage?.output_tokens ?? 0;
                     this.usage.cacheRead += ev.usage?.cache_read_input_tokens ?? 0;
@@ -217,7 +328,7 @@ export class ClaudeSession {
                 }
             });
             child.stderr.on("data", (d) => { stderr += d.toString(); });
-            child.on("error", (e) => { ok = false; ui.error(`não consegui executar o claude: ${e.message}`); });
+            child.on("error", (e) => { ok = false; failure.spawnError = e.message; ui.error(`não consegui executar o claude: ${e.message}`); });
             child.on("close", (code, signal) => {
                 this.child = null;
                 interrupted = signal === "SIGINT" || code === 130 || this.aborted;
@@ -227,9 +338,16 @@ export class ClaudeSession {
                     if (stderr.trim())
                         ui.error(stderr.trim().slice(0, 600));
                 }
-                else if (code === 0)
+                else if (code === 0) {
                     this.started = true;
+                    this.pendingHandoff = "";
+                }
                 turn.finished = ok && !interrupted && code === 0;
+                if (!ok && !interrupted) {
+                    Object.assign(failure, { stderr, code });
+                    const why = failure.spawnError ?? (failure.result || stderr.trim() || `claude saiu com código ${code}`);
+                    this.lastFailure = { kind: classifyClaudeCliFailure(failure), message: shortError(why) };
+                }
                 if (interrupted)
                     ui.warn("⏹ interrompido");
                 ui.turnEnd(ok && !interrupted);

package/dist/agent/context.js

@@ -1,3 +1,4 @@
+import { providerFor } from "../provider/index.js";
 /** Imagem em base64 tem megabytes, mas custa ~1,6 mil tokens: troca o conteúdo por um marcador antes de medir ou resumir. */
 const stubImages = (_k, v) => (v && typeof v === "object" && (v.type === "image" || v.type === "document") && v.source ? { type: v.type, note: "x".repeat(6400) } : v);
 export const estimateTokens = (msgs) => Math.ceil(JSON.stringify(msgs, stubImages).length / 4);
@@ -19,7 +20,7 @@ export function trimOldToolResults(msgs, keep = 8) {
     });
 }
 /** Fase 2: resume o meio da conversa via LLM, mantendo o início e os últimos turnos. */
-export async function summarizeMiddle(client, model, msgs, keepTail = 6) {
+export async function summarizeMiddle(model, msgs, keepTail = 6) {
     if (msgs.length <= keepTail + 2)
         return msgs;
     let cut = msgs.length - keepTail;
@@ -31,9 +32,11 @@ export async function summarizeMiddle(client, model, msgs, keepTail = 6) {
     const head = msgs.slice(0, 1);
     const middle = msgs.slice(1, cut);
     const tail = msgs.slice(cut);
-    const res = await client.messages.create({
+    // Raciocínio desligado: num endpoint com raciocínio ele comeria o orçamento do resumo.
+    const res = await providerFor(model).send({
         model,
-        max_tokens: 2000,
+        maxTokens: 2000,
+        thinking: false,
         system: "Resuma a conversa de um agente de programação. Preserve: objetivo, decisões, arquivos/símbolos tocados, erros encontrados, estado atual e próximos passos. Seja denso.",
         messages: [{ role: "user", content: JSON.stringify(middle, (_k, v) => (v && typeof v === "object" && (v.type === "image" || v.type === "document") && v.source ? { type: v.type, note: "[anexo omitido]" } : v)).slice(0, 150_000) }],
     });

package/dist/agent/loop.js

@@ -1,25 +1,30 @@
-import Anthropic from "@anthropic-ai/sdk";
 import { toApiTools, execTool, isConcurrent } from "../tools/registry.js";
 import { estimateTokens, summarizeMiddle, trimOldToolResults } from "./context.js";
 import { ui as terminalUi } from "../ui/ui.js";
-import { initialModel } from "../model.js";
+import { initialEffort, initialModel } from "../model.js";
+import { providerFor } from "../provider/index.js";
+import { compactAtFor, resolveModel } from "../provider/resolve.js";
+import { fallbackStatus } from "../engine.js";
+import { activateFallback, classifyAnthropicError, fallbackWarning, shortError, triggersFallback } from "../provider/fallback.js";
 import { fmtBytes, findImages, imageBlock, splitOversize } from "../util/images.js";
 export const MODEL = initialModel();
-const COMPACT_AT = Number(process.env.BRITO_COMPACT_TOKENS ?? 120_000);
 export class Agent {
     system;
     ctx;
     opts;
-    client = new Anthropic();
     messages = [];
     usage = { input: 0, output: 0, cacheRead: 0, steps: 0 };
     /** tamanho do contexto na última requisição (alimenta a barra de status) */
     contextTokens = 0;
     /** troca em runtime via `/model`; vale a partir da próxima requisição */
     model;
+    /** esforço de raciocínio (`/reasoning`); `none` desliga o raciocínio em endpoints que permitem */
+    effort = initialEffort();
     lastTurn = null;
     /** últimos turnos (o mais novo por último): o anterior dá contexto a correções do usuário */
     recentTurns = [];
+    /** turnos ainda não entregues ao claude CLI: na volta para ele, viram o contexto do próximo prompt (`handoff`) */
+    unsentTurns = [];
     maxSteps;
     log;
     ui;
@@ -58,6 +63,7 @@ export class Agent {
         const turn = { messages: [], toolCalls: 0, errors: 0, finished: false };
         this.lastTurn = turn;
         this.recentTurns = [...this.recentTurns, turn].slice(-3);
+        this.unsentTurns.push(turn);
         const push = (m) => { this.messages.push(m); turn.messages.push(m); };
         // Imagens arrastadas para o terminal chegam como caminhos no texto: anexa como blocos `image`. O registro do turno
         // (usado na reflexão) guarda só o texto, para não carregar base64.
@@ -65,6 +71,9 @@ export class Agent {
         for (const i of tooBig)
             this.log(`⚠ ${i.name} passa do limite da API e não foi anexado`);
         if (ok.length) {
+            const target = resolveModel(this.model);
+            if (target.kind === "openai" && !target.profile.vision)
+                this.log(`⚠ o modelo ${target.label} não aceita imagens; ${ok.length > 1 ? `${ok.length} anexos não foram enviados` : "o anexo não foi enviado"} (vision: true no perfil liga)`);
             this.log(`📎 ${ok.map((i) => `${i.name} (${fmtBytes(i.bytes)})`).join(", ")} anexado${ok.length > 1 ? "s" : ""}`);
             this.messages.push({ role: "user", content: [...ok.map(imageBlock), { type: "text", text: userText }] });
             turn.messages.push({ role: "user", content: userText });
@@ -76,29 +85,30 @@ export class Agent {
         for (let step = 0; step < this.maxSteps; step++) {
             if (signal?.aborted)
                 throw new Error("abort");
-            const stream = this.client.messages.stream({
-                model: this.model,
-                max_tokens: 8192,
-                system: [{ type: "text", text: typeof this.system === "function" ? this.system() : this.system, cache_control: { type: "ephemeral" } }],
-                tools: toApiTools(this.opts.tools),
-                messages: this.messages,
-            }, { signal });
-            if (!this.opts.quiet)
-                stream.on("text", (t) => this.ui.text(t));
-            const msg = await stream.finalMessage();
-            this.contextTokens = msg.usage.input_tokens + (msg.usage.cache_read_input_tokens ?? 0) + (msg.usage.cache_creation_input_tokens ?? 0);
-            this.usage.input += msg.usage.input_tokens + (msg.usage.cache_read_input_tokens ?? 0) + (msg.usage.cache_creation_input_tokens ?? 0);
-            this.usage.output += msg.usage.output_tokens;
-            this.usage.cacheRead += msg.usage.cache_read_input_tokens ?? 0;
+            const msg = await this.callModel({ signal, onText: this.opts.quiet ? undefined : (t) => this.ui.text(t), onThinking: this.opts.quiet ? undefined : (t) => this.ui.thinking(t) });
+            this.contextTokens = msg.usage.input;
+            this.usage.input += msg.usage.input;
+            this.usage.output += msg.usage.output;
+            this.usage.cacheRead += msg.usage.cacheRead;
             this.usage.steps++;
-            push({ role: "assistant", content: msg.content });
+            if (msg.stopReason === "max_tokens")
+                this.log("⚠ resposta cortada pelo limite de tokens; peça para continuar ou desligue o raciocínio (/reasoning none)");
+            // Mensagem vazia não entra no histórico: a API da Anthropic recusaria o próximo turno.
+            if (msg.content.length)
+                push({ role: "assistant", content: msg.content });
             const text = msg.content.flatMap((b) => (b.type === "text" ? [b.text] : [])).join("");
             if (text)
                 finalText = text;
             if (!this.opts.quiet)
                 this.ui.textEnd();
             const uses = msg.content.filter((b) => b.type === "tool_use");
-            if (msg.stop_reason !== "tool_use" || uses.length === 0) {
+            if (uses.length && msg.stopReason !== "tool_use") {
+                // Chamada de tool cortada no meio: fecha cada uma com erro para o histórico continuar válido.
+                push({ role: "user", content: uses.map((u) => ({ type: "tool_result", tool_use_id: u.id, content: "Chamada cortada antes de terminar (limite de tokens); não foi executada.", is_error: true })) });
+                turn.finished = true;
+                return finalText;
+            }
+            if (msg.stopReason !== "tool_use" || uses.length === 0) {
                 turn.finished = true;
                 return finalText;
             }
@@ -126,14 +136,50 @@ export class Agent {
         this.ui.warn("Limite de passos atingido.");
         return finalText || "(limite de passos atingido sem resposta final)";
     }
+    /**
+     * Um passo do loop principal. Se o Claude falha por conta/capacidade e o qwen está pronto, troca o modelo da sessão
+     * (uma vez só) e repete o mesmo passo: o histórico está intacto, porque a falha veio antes de a resposta entrar nele.
+     */
+    async callModel(hooks) {
+        // Num endpoint com raciocínio, pensar e responder dividem o mesmo orçamento: dobra para não cortar a resposta.
+        const target = resolveModel(this.model);
+        const thinking = this.effort !== "none";
+        try {
+            return await providerFor(this.model).send({
+                model: this.model,
+                maxTokens: target.kind === "openai" && thinking ? 16_384 : 8192,
+                system: typeof this.system === "function" ? this.system() : this.system,
+                tools: toApiTools(this.opts.tools),
+                messages: this.messages,
+                thinking,
+            }, hooks);
+        }
+        catch (e) {
+            const fb = this.opts.fallback;
+            if (!fb || fb.active || hooks.signal?.aborted || target.kind !== "anthropic")
+                throw e;
+            const kind = classifyAnthropicError(e);
+            if (!triggersFallback(kind))
+                throw e;
+            const status = fallbackStatus(this.model, process.env);
+            if (!status.ready)
+                throw e;
+            const why = shortError(e);
+            this.ui.warn(fallbackWarning(kind, why, status.label));
+            activateFallback(fb, `${kind} (${why})`);
+            this.model = status.name;
+            await this.compactIfNeeded();
+            return this.callModel(hooks);
+        }
+    }
     async compactIfNeeded() {
-        if (estimateTokens(this.messages) < COMPACT_AT)
+        if (estimateTokens(this.messages) < compactAtFor(this.model))
             return;
         this.messages = trimOldToolResults(this.messages);
-        if (estimateTokens(this.messages) < COMPACT_AT)
+        if (estimateTokens(this.messages) < compactAtFor(this.model))
             return;
         this.log("compactando contexto…");
-        this.messages = await summarizeMiddle(this.client, this.model, this.messages);
+        this.messages = await summarizeMiddle(this.model, this.messages);
         this.contextTokens = estimateTokens(this.messages); // até a próxima chamada real, a barra não fica com o valor antigo
     }
 }