kafox-cli 0.6.0 → 0.8.0

package/README.md

@@ -12,7 +12,7 @@ npm install -g kafox-cli
 O comando instalado e `kafox`. Alternativa sem npm:
 
 ```bash
-npm install -g https://kafox.pypag.com/static/downloads/kafox-cli-0.3.0.tgz
+npm install -g https://kafox.pypag.com/static/downloads/kafox-cli-0.8.0.tgz
 ```
 
 Requisito: Node.js 22.5+.
@@ -23,9 +23,10 @@ Requisito: Node.js 22.5+.
 kafox login
 ```
 
-A CLI mostra um codigo e a URL `https://kafox.pypag.com/cli?code=...`. Abra no
-navegador, entre na sua conta e clique em **Autorizar**. A sessao fica em
-`~/.kafox/token.json` (permissao 600).
+O terminal vira uma tela de login (arte grande em cima, link no centro): abra a
+URL `https://kafox.pypag.com/cli?code=...`, entre na sua conta e clique em
+**Autorizar**. A sessao fica em `~/.kafox/token.json` (permissao 600). No primeiro
+`kafox` sem sessao ele pergunta se quer entrar e abre a mesma tela.
 
 ## Comandos
 
@@ -39,17 +40,70 @@ navegador, entre na sua conta e clique em **Autorizar**. A sessao fica em
 | `kafox balance` | saldo atual |
 | `kafox key` | cria uma API key |
 | `kafox ask "pergunta" [-m modelo]` | pergunta ao gateway |
+| `kafox agent "objetivo" [-y] [--max-steps 12] [--json]` | roda o agente sem TUI (script/CI) |
+| `kafox history [n]` | lista as conversas salvas (titulo - data + como retomar) |
+| `kafox resume [codigo]` | retoma uma conversa; sem codigo abre o seletor na tela |
+| `kafox continue` / `kafox -c` | volta para a conversa mais recente |
 | `kafox status` | conta, saldo e gateway |
 | `kafox theme` | seletor de tema |
 | `kafox background [url]` | imagem de fundo do terminal |
 | `kafox compact` / `clear` | compacta / limpa o contexto do REPL |
 
+## Conversas salvas
+
+Toda conversa fica em `~/.kafox/chats/<codigo>.json`. Ao sair com **Ctrl+C** a
+CLI mostra o codigo:
+
+```
+  Retome esta conversa: kafox --resume 3f1c9a0b
+```
+
+`kafox history` lista da mais nova para a mais antiga, cada uma com o comando
+que retoma (e `kafox history 20` mostra so as 20 ultimas):
+
+```
+hello world em python, tem como fazer um sis... - 28/10
+kafox resume 3f1c9a0b
+
+nessa cli que voce ve, tem como fazer alguma co... - 27/10
+kafox resume 8ad2f19c
+```
+
+`kafox resume` (sem codigo) abre o seletor com os titulos das conversas — setas
+ou a roda do mouse navegam, clique ou Enter retomam a conversa escolhida.
+`kafox resume 3f1c` aceita o codigo inteiro ou so o comeco dele, e
+`kafox continue` (ou `-c`) vai direto para a ultima.
+
+## Agentes e subagentes
+
+O agente tem a ferramenta `spawn_subagent`: ele lança subagentes com objetivo
+próprio, cada um num contexto separado, e recebe só o relatório final. Vão até
+3 tarefas por chamada e as independentes rodam em paralelo. Por padrão o
+subagente só lê (`read_file`, `list_dir`); escrever, editar ou executar exige
+declarar a ferramenta na tarefa — e continua passando pela aprovação normal
+(ou pelo `/allow`).
+
+```bash
+kafox agent "revise src/agent.js e aponte bugs" --max-steps 8
+kafox agent "rode os testes do backend e resuma as falhas" -y --json
+```
+
+Para ver o que os subagentes da sessão fizeram (objetivo, ferramentas, tempo e
+se terminaram), use `/agents` — o mesmo comando funciona no REPL e na TUI.
+
 Na interface: digite `/` para o menu (↑/↓ navega, Tab completa, Enter executa),
 `/model` abre o seletor de modelo e `/theme` o de tema (↑/↓, clique do mouse,
 Enter aplica, Esc cancela). A resposta chega em streaming, com bloco `Thinking`
 quando o modelo manda o raciocinio. PgUp/PgDn ou a roda do mouse rolam a conversa;
 Ctrl+Y copia a ultima resposta e F2 solta o mouse para selecionar texto.
 
+Enquanto o modelo trabalha a caixa de texto mostra `trabalhando...` com os
+pontinhos correndo, e o nome do modelo aparece fora dela, na linha de baixo.
+Se a rede cair (`fetch failed`), a CLI tenta de novo sozinha ate 20 vezes
+dobrando a espera (3s, 6s, 12s, 24s... ate 60s) e mostra a contagem na linha do
+modelo; **Esc** cancela a espera na hora. O agente nao tem limite de passos: ele
+continua ate terminar.
+
 Nao precisa esperar a resposta para escrever de novo: **Enter enfileira** a
 mensagem (a fila aparece acima do input e roda em ordem assim que a atual
 termina). Para parar a IA na hora, **Esc duas vezes** — o primeiro Esc so avisa,
@@ -127,7 +181,9 @@ motivo do erro quando falha) e `/mcp` lista tudo; `/mcp reload` reconecta.
 - `~/.kafox/mcp.json` guarda os servidores MCP.
 
 A CLI so responde se a conta tiver saldo; sem credito ela avisa e nao chama o
-gateway.
+gateway. Nao existe limite de mensagens por chamada nem de passos do agente: a
+conversa continua ate o modelo terminar (ou ate voce apertar Esc). O unico freio
+e o saldo.
 
 ## Escopo
 

package/bin/kafox.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+const chalk = require("chalk");
 const { Command } = require("commander");
 const { version } = require("../package.json");
 const { runREPL, compact, clearContext, showStatus } = require("../src/cli");
@@ -6,6 +7,7 @@ const { login, logout, whoami, createKey } = require("../src/auth");
 const { listModels, showBalance, showPricing } = require("../src/models");
 const { ask } = require("../src/gateway");
 const { runTheme, setContentBackground } = require("../src/theme");
+const { runHeadless } = require("../src/runner");
 
 const program = new Command();
 
@@ -16,21 +18,102 @@ program
     "-y, --allow-all",
     "abre ja aprovando tudo: ferramentas de arquivo, comando e MCP sem pedir aprovacao"
   )
+  .option(
+    "--resume [codigo]",
+    "retoma uma conversa salva (o codigo aparece no Ctrl+C e no `kafox history`)"
+  )
+  .option("-c, --continue", "retoma a conversa mais recente")
   .version(version);
 
+/**
+ * `kafox history [n]`: lista as conversas salvas, da mais nova para a mais
+ * antiga, no formato "titulo - 28/10" seguido do comando para retomar.
+ * Sem argumento lista todas; `kafox history 20` mostra as 20 ultimas.
+ */
+function printHistory(limit) {
+  const sessions = require("../src/sessions");
+  const chats = sessions.list();
+  if (!chats.length) {
+    console.log("Nenhuma conversa salva ainda.");
+    console.log(chalk.dim("Comece um chat com `kafox` e saia com Ctrl+C para ele ser salvo."));
+    return;
+  }
+
+  const wanted = Number.parseInt(String(limit ?? ""), 10);
+  const shown =
+    Number.isFinite(wanted) && wanted > 0 ? chats.slice(0, wanted) : chats;
+
+  for (const chat of shown) {
+    const when = sessions.dayMonth(chat.updatedAt);
+    console.log(`${chalk.bold(chat.title)}${when ? ` - ${when}` : ""}`);
+    console.log(chalk.cyan(`kafox resume ${chat.id}`));
+    console.log("");
+  }
+  if (shown.length < chats.length) {
+    console.log(
+      chalk.dim(`${shown.length} de ${chats.length} conversa(s). Use \`kafox history\` para ver todas.`)
+    );
+  }
+}
+
 program.command("login").description("Login with your Kafox account (device code SSO)").action(login);
 program.command("logout").description("End the CLI session").action(logout);
 program.command("whoami").description("Show the account linked to this CLI").action(whoami);
-program.command("models").description("List available models and prices").action(listModels);
+program.command("models").description("List available models").action(listModels);
 program.command("balance").description("Show current balance").action(showBalance);
 program.command("pricing").description("Show recharge packages").action(showPricing);
 program.command("key").description("Create an API key for this CLI").action(createKey);
 program.command("ask").argument("[question...]", "Question").option("-m, --model <id>", "Model").action(ask);
+program
+  .command("agent")
+  .description("Run the agent without the TUI (tools, subagents, scripting)")
+  .argument("<objective...>", "Objetivo do agente")
+  .option("-m, --model <id>", "Model")
+  // -y/--allow-all é global (declarado no programa): declarar de novo aqui
+  // fazia o commander esconder a flag e o agente nunca rodava liberado.
+  .option("--max-steps <n>", "limite de passos (padrao: sem limite)", "0")
+  .option("--json", "imprime só o resultado em JSON")
+  .option("-q, --quiet", "esconde o progresso das ferramentas")
+  .action(async (objective, options) => {
+    const globals = program.opts();
+    const payload = await runHeadless({
+      prompt: objective.join(" "),
+      model: options.model,
+      allowAll: Boolean(options.allowAll || globals.allowAll),
+      maxSteps: Number(options.maxSteps) > 0 ? Number(options.maxSteps) : Infinity,
+      json: Boolean(options.json),
+      quiet: Boolean(options.quiet),
+    });
+    if (!payload.ok) process.exitCode = 1;
+  });
 program.command("theme").description("Open the theme selector").action(runTheme);
 program.command("background").description("Set terminal background image (URL)").argument("[url]", "Image URL").action(setContentBackground);
+program
+  .command("history [quantidade]")
+  .alias("historico")
+  .description("Lista as conversas salvas e como retomar (ex.: kafox history 20)")
+  .action((quantidade) => printHistory(quantidade));
+
+program
+  .command("resume [codigo]")
+  .description("Retoma uma conversa salva (sem codigo abre o seletor na tela)")
+  .action((codigo) =>
+    runREPL({ allowAll: Boolean(program.opts().allowAll), resume: codigo || "pick" })
+  );
+
+program
+  .command("continue")
+  .alias("c")
+  .description("Continua a conversa mais recente")
+  .action(() => runREPL({ allowAll: Boolean(program.opts().allowAll), resume: "last" }));
 program.command("compact").description("Compact the current conversation context").action(compact);
 program.command("clear").description("Clear the conversation context").action(clearContext);
 program.command("status").description("Show account, balance and gateway status").action(showStatus);
 
-program.action((options) => runREPL({ allowAll: Boolean(options.allowAll) }));
+program.action((options) =>
+  runREPL({
+    allowAll: Boolean(options.allowAll),
+    resume: options.continue ? "last" : options.resume || null,
+  })
+);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kafox-cli",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Kafox CLI: TUI com streaming, thinking, edit com diff, agent tools (files/shell), MCP e temas",
   "bin": {
     "kafox": "bin/kafox.js"

package/src/agent.js

@@ -7,8 +7,21 @@ const {
   previewToolChange,
   summarizeOutput,
 } = require("./tools");
+const {
+  SUBAGENT_TOOL,
+  SUBAGENT_TOOL_NAME,
+  MAX_DEPTH,
+  normalizeTasks,
+  subagentPrompt,
+  describeSubagentCall,
+  recordRun,
+  DEFAULT_MAX_STEPS,
+} = require("./subagents");
 
-const MAX_STEPS = 10;
+// Sem teto de passos: o agente continua ate terminar (ou ate o usuario parar
+// com Esc). `maxSteps` so vale quando alguem pede um limite de proposito.
+const MAX_STEPS = Infinity;
+const MAX_SUBAGENT_REPORT_CHARS = 6000;
 
 function parseArgs(raw) {
   if (!raw) return {};
@@ -28,12 +41,160 @@ function systemPrompt(cwd, model) {
     "Ferramentas locais: read_file, list_dir, write_file, edit_file, run_command.",
     "Para mudar um arquivo existente use edit_file (troca de trecho exato); write_file e para arquivo novo ou reescrita completa.",
     "Ferramentas com nome mcp__<servidor>__<ferramenta> vem de servidores MCP conectados: use quando ajudarem.",
+    `spawn_subagent lanca subagentes com objetivo proprio em contexto separado (ate 3 em paralelo). Use para investigar varios pontos ao mesmo tempo, para auditoria/teste ou para tarefa longa; cada subagente devolve so o relatorio final.`,
     "Nunca invente conteudo de arquivo: leia antes de editar. Prefira caminhos relativos.",
     "Quem escreve ou executa passa por aprovacao do usuario, entao explique em uma frase o que vai fazer.",
     "Responda no idioma do usuario, de forma direta, com Markdown.",
   ].join("\n");
 }
 
+/**
+ * Roda um subagente: contexto proprio, ferramentas limitadas e relatorio final.
+ * Os eventos (onSubagentEvent) deixam a TUI mostrar o progresso ao vivo.
+ */
+async function runSubagentTask({
+  task,
+  index,
+  total,
+  model,
+  cwd,
+  approve,
+  autoAllowed,
+  signal,
+  depth,
+  onSubagentEvent,
+}) {
+  const started = Date.now();
+  const baseTools = TOOL_SPECS.filter((spec) => task.tools.includes(spec.function.name));
+  // Um nivel de subagente: o filho nao abre netos (evita recursao descontrolada).
+  const nested = [];
+
+  onSubagentEvent?.({
+    index,
+    total,
+    objective: task.objective,
+    phase: "start",
+    tools: task.tools,
+  });
+
+  let lastText = "";
+  try {
+    const result = await runAgent({
+      messages: [
+        {
+          role: "system",
+          content: subagentPrompt({ objective: task.objective, context: task.context, cwd, depth }),
+        },
+        { role: "user", content: task.objective },
+      ],
+      model,
+      cwd,
+      baseTools,
+      extraTools: nested,
+      maxSteps: task.maxSteps || DEFAULT_MAX_STEPS,
+      approve: approve
+        ? (name, args, context) =>
+            approve(name, args, { ...context, subagent: { index, objective: task.objective } })
+        : undefined,
+      autoApprove: autoAllowed,
+      signal,
+      depth: depth + 1,
+      subagents: depth + 1 < MAX_DEPTH,
+      onSubagentEvent,
+      onText: (chunk) => {
+        lastText += chunk;
+        onSubagentEvent?.({ index, total, phase: "text", text: chunk, objective: task.objective });
+      },
+      onReasoning: (chunk) =>
+        onSubagentEvent?.({ index, total, phase: "thought", text: chunk, objective: task.objective }),
+      onToolStart: ({ name, label }) =>
+        onSubagentEvent?.({ index, total, phase: "tool", tool: name, text: label, objective: task.objective }),
+      onToolResult: ({ name, ok }) =>
+        onSubagentEvent?.({ index, total, phase: "tool-done", tool: name, ok, objective: task.objective }),
+    });
+
+    const report = String(result.text || lastText || "").trim();
+    const body = report
+      ? report.slice(0, MAX_SUBAGENT_REPORT_CHARS)
+      : result.ok
+        ? "(subagente terminou sem texto final)"
+        : `(subagente falhou: ${result.error || "erro desconhecido"})`;
+    recordRun({
+      objective: task.objective,
+      tools: task.tools,
+      ok: Boolean(result.ok),
+      ms: Date.now() - started,
+      steps: result.steps || 0,
+      report: body,
+    });
+    onSubagentEvent?.({
+      index,
+      total,
+      objective: task.objective,
+      phase: "done",
+      ok: Boolean(result.ok),
+      ms: Date.now() - started,
+    });
+    return { index, objective: task.objective, ok: Boolean(result.ok), body, ms: Date.now() - started };
+  } catch (error) {
+    onSubagentEvent?.({
+      index,
+      total,
+      objective: task.objective,
+      phase: "done",
+      ok: false,
+      ms: Date.now() - started,
+    });
+    recordRun({
+      objective: task.objective,
+      tools: task.tools,
+      ok: false,
+      ms: Date.now() - started,
+      report: error.message,
+    });
+    return {
+      index,
+      objective: task.objective,
+      ok: false,
+      body: `(subagente falhou: ${error.message})`,
+      ms: Date.now() - started,
+    };
+  }
+}
+
+/** Dispara as tarefas (o que for independente roda em paralelo) e junta os relatorios. */
+async function runSubagents({ args, model, cwd, approve, autoAllowed, signal, depth, onSubagentEvent }) {
+  const tasks = normalizeTasks(args);
+  if (!tasks.length) {
+    return "Nenhuma tarefa recebida: informe `tasks: [{objective}]` (ou `objective`) para o subagente.";
+  }
+
+  const results = await Promise.all(
+    tasks.map((task, index) =>
+      runSubagentTask({
+        task,
+        index: index + 1,
+        total: tasks.length,
+        model: args?.model || model,
+        cwd,
+        approve,
+        autoAllowed,
+        signal,
+        depth,
+        onSubagentEvent,
+      })
+    )
+  );
+
+  return results
+    .map(
+      (result) =>
+        `[subagente ${result.index}/${results.length}] objetivo: ${result.objective}\n` +
+        `status: ${result.ok ? "ok" : "falhou"} · ${result.ms}ms\n${result.body}`
+    )
+    .join("\n\n---\n\n");
+}
+
 /**
  * Roda o loop: modelo -> tool calls -> resultados -> modelo, ate a resposta final.
  * Ferramenta que escreve, edita, executa ou vem de MCP passa por `approve`
@@ -46,26 +207,37 @@ async function runAgent({
   approve,
   autoApprove = false,
   extraTools = [],
+  baseTools = TOOL_SPECS,
   mcp = null,
   signal,
-  maxSteps = MAX_STEPS,
+  maxSteps = Infinity,
+  depth = 0,
+  subagents = true,
   onText,
   onReasoning,
   onToolStart,
   onToolResult,
+  onSubagentEvent,
+  onRetry,
 } = {}) {
   const conversation = messages.map((message) => ({ ...message }));
   if (!conversation.length || conversation[0].role !== "system") {
     conversation.unshift({ role: "system", content: systemPrompt(cwd, model) });
   }
 
-  const tools = extraTools.length ? [...TOOL_SPECS, ...extraTools] : TOOL_SPECS;
+  // O subagente entra na lista de ferramentas enquanto a profundidade permitir.
+  const canSpawn = subagents && depth < MAX_DEPTH;
+  const tools = [
+    ...baseTools,
+    ...extraTools,
+    ...(canSpawn ? [SUBAGENT_TOOL] : []),
+  ];
   // `autoApprove` pode ser um valor ou uma funcao: o "Permitir sempre" da TUI
   // liga o modo no meio do loop, e o resto da execucao ja nao pergunta mais.
   const autoAllowed = typeof autoApprove === "function" ? autoApprove : () => Boolean(autoApprove);
   let last = { text: "", reasoning: "", ms: 0, usage: null };
 
-  for (let step = 0; step < maxSteps; step += 1) {
+  for (let step = 0; step < (maxSteps || Infinity); step += 1) {
     // Esc duas vezes na TUI aborta o signal: nao comeca outro passo.
     if (signal?.aborted) {
       return { ok: true, aborted: true, text: last.text, messages: conversation, steps: step };
@@ -79,6 +251,7 @@ async function runAgent({
       signal,
       onDelta: onText,
       onReasoning,
+      onRetry,
     });
 
     if (!result.ok) {
@@ -123,7 +296,11 @@ async function runAgent({
       const name = call?.function?.name || "";
       const args = parseArgs(call?.function?.arguments);
       const fromMcp = Boolean(mcp?.has?.(name));
-      const needsApproval = APPROVAL_REQUIRED.has(name) || fromMcp;
+      const isSubagent = name === SUBAGENT_TOOL_NAME;
+      // O subagente em si nao pede aprovacao: quem escreve/executa dentro dele
+      // continua passando pelo portao normal.
+      const needsApproval = !isSubagent && (APPROVAL_REQUIRED.has(name) || fromMcp);
+      const callId = call.id || `call_${step}_${name}`;
 
       let change = null;
       try {
@@ -132,13 +309,18 @@ async function runAgent({
         change = null;
       }
 
+      const label = isSubagent ? describeSubagentCall(args) : describeToolCall(name, args);
+      const tasks = isSubagent ? normalizeTasks(args) : null;
+
       onToolStart?.({
+        id: callId,
         name,
         args,
-        label: describeToolCall(name, args),
+        label,
         change,
         fromMcp,
         needsApproval,
+        subagent: tasks ? { count: tasks.length, objectives: tasks.map((task) => task.objective) } : null,
       });
 
       const gate = needsApproval && !autoAllowed();
@@ -151,6 +333,17 @@ async function runAgent({
       let output;
       if (!allowed) {
         output = "O usuario negou a execucao desta ferramenta. Peca instrucoes se precisar.";
+      } else if (isSubagent) {
+        output = await runSubagents({
+          args,
+          model,
+          cwd,
+          approve,
+          autoAllowed,
+          signal,
+          depth,
+          onSubagentEvent: (event) => onSubagentEvent?.({ ...event, id: callId }),
+        });
       } else {
         try {
           output = await executeTool(name, args, { cwd, mcp });
@@ -160,6 +353,7 @@ async function runAgent({
       }
 
       onToolResult?.({
+        id: callId,
         name,
         args,
         output,
@@ -169,11 +363,12 @@ async function runAgent({
         fromMcp,
         ms: Date.now() - toolStarted,
         summary: summarizeOutput(output),
+        subagent: tasks ? { count: tasks.length } : null,
       });
 
       conversation.push({
         role: "tool",
-        tool_call_id: call.id || `call_${step}`,
+        tool_call_id: callId,
         content: String(output),
       });
     }
@@ -181,10 +376,10 @@ async function runAgent({
 
   return {
     ok: false,
-    error: `Limite de ${maxSteps} passos do agente atingido. Tente dividir o pedido.`,
+    error: `Limite de ${maxSteps} passos do agente atingido.`,
     ...last,
     messages: conversation,
   };
 }
 
-module.exports = { runAgent, MAX_STEPS, systemPrompt };
+module.exports = { runAgent, runSubagents, MAX_STEPS, systemPrompt };

package/src/auth.js

@@ -20,12 +20,11 @@ async function ensureSession() {
   return null;
 }
 
+/**
+ * Login por device code. Com TTY abre a tela cheia (logo grande, link no meio);
+ * sem TTY (pipe/CI) mantem o fluxo de texto, que continua funcionando.
+ */
 async function login() {
-  console.log(MASCOT);
-  console.log(
-    chalk.cyan("  Kafox CLI - login by device code (SSO)\n")
-  );
-
   const res = await fetchApi("/api/cli/device", {
     method: "POST",
     body: "{}",
@@ -36,10 +35,15 @@ async function login() {
     return;
   }
 
-  console.log(
-    chalk.bold("\n  Open this URL in your browser to approve:\n") +
-    chalk.cyan(`    ${storage.getApiUrl()}/cli?code=${data.user_code}\n`)
-  );
+  const url = `${storage.getApiUrl()}/cli?code=${data.user_code}`;
+
+  if (process.stdout.isTTY && process.stdin.isTTY) {
+    return loginWithScreen({ url, data });
+  }
+
+  console.log(MASCOT);
+  console.log(chalk.cyan("  Kafox CLI - login by device code (SSO)\n"));
+  console.log(chalk.bold("  Open this URL in your browser to approve:\n") + chalk.cyan(`    ${url}\n`));
   console.log(`  Code: ${chalk.bold(data.user_code)}  (expires in ${data.expires_in}s)\n`);
 
   const interval = Math.max(1, data.interval) * 1000;
@@ -50,32 +54,75 @@ async function login() {
     process.stdout.write(`\r  Waiting for approval${".".repeat(dots % 4)}   `);
     dots += 1;
     await new Promise((r) => setTimeout(r, interval));
-    try {
-      const poll = await fetchApi(`/api/cli/poll/${encodeURIComponent(data.device_code)}`);
-      const pd = await poll.json().catch(() => ({}));
-      if (poll.status === 200 && pd.status === "approved") {
-        const previous = storage.getToken() || {};
-        storage.setToken({ session: pd.session, csrf: previous.csrf });
-        console.log(
-          chalk.green("\n  Approved! Session saved to ~/.kafox/token.json")
-        );
-        return;
-      }
-      if (pd.status === "denied" || poll.status === 403) {
-        console.log(chalk.red("\n  Login denied."));
-        return;
-      }
-      if (poll.status === 404 || poll.status === 410) {
-        console.log(chalk.red("\n  Device code expired. Run `kafox login` again."));
-        return;
-      }
-    } catch {
-      // ignore transient errors, keep polling
+    const outcome = await pollDevice(data);
+    if (outcome.ok) {
+      console.log(chalk.green("\n  Approved! Session saved to ~/.kafox/token.json"));
+      return;
+    }
+    if (outcome.stop) {
+      console.log(chalk.red(`\n  ${outcome.error}`));
+      return;
     }
   }
   console.log(chalk.red("\n  Device code expired. Run `kafox login` again."));
 }
 
+/** Uma consulta do device code; grava a sessao quando aprovada. */
+async function pollDevice(data) {
+  let poll;
+  try {
+    poll = await fetchApi(`/api/cli/poll/${encodeURIComponent(data.device_code)}`);
+  } catch {
+    return { ok: false, stop: false };
+  }
+  const pd = await poll.json().catch(() => ({}));
+  if (poll.status === 200 && pd.status === "approved") {
+    const previous = storage.getToken() || {};
+    storage.setToken({ session: pd.session, csrf: previous.csrf });
+    return { ok: true, stop: true };
+  }
+  if (pd.status === "denied" || poll.status === 403) {
+    return { ok: false, stop: true, error: "Login denied." };
+  }
+  if (poll.status === 404 || poll.status === 410) {
+    return { ok: false, stop: true, error: "Device code expired. Run `kafox login` again." };
+  }
+  return { ok: false, stop: false };
+}
+
+async function loginWithScreen({ url, data }) {
+  const { runLoginScreen } = require("./login-screen");
+  const { version } = require("../package.json");
+  const theme = storage.getConfig().theme || "default";
+
+  const result = await runLoginScreen({
+    url,
+    code: data.user_code,
+    interval: data.interval,
+    expiresIn: data.expires_in,
+    theme,
+    version,
+    poll: async () => {
+      const outcome = await pollDevice(data);
+      if (outcome.ok) return { ok: true };
+      if (outcome.stop) return { ok: false, error: outcome.error };
+      return { ok: false };
+    },
+  });
+
+  if (result.ok) {
+    console.log(chalk.green("  Aprovado! Sessao salva em ~/.kafox/token.json"));
+    console.log(chalk.dim("  Bom proveito.\n"));
+    return true;
+  }
+  if (result.cancelled) {
+    console.log(chalk.dim("  Login cancelado.\n"));
+    return false;
+  }
+  console.log(chalk.red(`  ${result.error || "Nao foi possivel entrar"}.\n`));
+  return false;
+}
+
 async function logout() {
   storage.clearToken();
   console.log(chalk.green("  Session ended."));