kafox-cli 0.7.0 → 0.9.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+.
@@ -41,12 +41,12 @@ URL `https://kafox.pypag.com/cli?code=...`, entre na sua conta e clique em
 | `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` | lista as conversas salvas (titulo + como retomar) |
+| `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 background [arquivo\|url]` | imagem de fundo da interface (`off` remove) |
 | `kafox compact` / `clear` | compacta / limpa o contexto do REPL |
 
 ## Conversas salvas
@@ -58,16 +58,32 @@ CLI mostra o codigo:
   Retome esta conversa: kafox --resume 3f1c9a0b
 ```
 
-`kafox history` lista tudo:
+`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 solicitado, usa arquivo e roda teste
-  kafox resume 3f1c9a0b
+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 mouse escolhem, Enter retoma. `kafox continue` (ou `-c`) vai direto para a
-ultima.
+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.
+
+A conversa guarda o modelo, o tema e o modo **rodar tudo**: se voce retomar um
+chat que estava com a aprovacao automatica ligada, ele volta ligado (e o
+contrario tambem). `kafox --allow-all` continua valendo por cima de tudo.
+
+## Imagem de fundo
+
+`/background ~/Imagens/ponte.jpg` (ou uma URL https) desenha a foto atras da
+conversa, com o texto por cima. Aceita **PNG** e **JPG**; a imagem e escurecida
+para nao atrapalhar a leitura e se ajusta sozinha ao tamanho do terminal.
+`/background off` remove, e a escolha fica em `~/.kafox/config.json`.
 
 ## Agentes e subagentes
 
@@ -176,7 +192,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

@@ -25,19 +25,35 @@ program
   .option("-c, --continue", "retoma a conversa mais recente")
   .version(version);
 
-/** `kafox history`: titulo de cada conversa e como retomar. */
-function printHistory() {
+/**
+ * `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;
   }
-  for (const chat of chats) {
-    console.log(`- ${chalk.bold(chat.title)}`);
-    console.log(`  kafox resume ${chat.id}`);
+
+  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);
@@ -73,10 +89,10 @@ program
 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")
+  .command("history [quantidade]")
   .alias("historico")
-  .description("Lista todas as conversas salvas")
-  .action(printHistory);
+  .description("Lista as conversas salvas e como retomar (ex.: kafox history 20)")
+  .action((quantidade) => printHistory(quantidade));
 
 program
   .command("resume [codigo]")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kafox-cli",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Kafox CLI: TUI com streaming, thinking, edit com diff, agent tools (files/shell), MCP e temas",
   "bin": {
     "kafox": "bin/kafox.js"
@@ -17,7 +17,8 @@
   "dependencies": {
     "chalk": "4.1.2",
     "commander": "12.1.0",
-    "inquirer": "8.2.6"
+    "inquirer": "8.2.6",
+    "jpeg-js": "^0.4.4"
   },
   "scripts": {
     "test": "node --test \"test/*.test.js\"",

package/src/cli.js

@@ -28,7 +28,7 @@ const COMMANDS = {
   "/agents": "lista os subagentes desta sessao (objetivo, ferramentas, tempo)",
   "/mcp": "list MCP servers and tools (/mcp reload reconecta)",
   "/allow": "aprovacao automatica nesta sessao (/allow off volta a perguntar)",
-  "/background": "set background image (modal asks for URL)",
+  "/background": "imagem de fundo (/background <arquivo|url>; off remove)",
   "/clear": "clear conversation context",
   "/compact": "compact conversation context",
   "/status": "show account, balance and gateway status",
@@ -315,8 +315,8 @@ async function runREPL(options = {}) {
   return runTUI({
     commands: COMMANDS,
     onCommand: handleCommand,
-    // /theme roda dentro da TUI (modal com preview); os demais abrem prompt no terminal.
-    interactiveCommands: new Set(["/login", "/key", "/background"]),
+    // /theme e /background rodam dentro da TUI; os demais abrem prompt no terminal.
+    interactiveCommands: new Set(["/login", "/key"]),
     autoApprove: Boolean(options?.allowAll),
     // kafox --resume <codigo> volta para a conversa salva em ~/.kafox/chats.
     resume: options?.resume || null,

package/src/sessions.js

@@ -40,6 +40,23 @@ function fileFor(id) {
   return path.join(chatsDir(), `${id}.json`);
 }
 
+/** Codigo digitado pelo usuario: so letras/numeros (sem caminho, sem "."). */
+function normalizeId(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "");
+}
+
+/** Data curta do chat: "2026-10-28T..." -> "28/10". */
+function dayMonth(value) {
+  const parsed = new Date(value || "");
+  if (Number.isNaN(parsed.getTime())) return "";
+  const day = String(parsed.getDate()).padStart(2, "0");
+  const month = String(parsed.getMonth() + 1).padStart(2, "0");
+  return `${day}/${month}`;
+}
+
 /** Titulo curto: primeira mensagem do usuario, em uma linha. */
 function titleFrom(messages, fallback = "") {
   const first = (messages || []).find(
@@ -52,7 +69,7 @@ function titleFrom(messages, fallback = "") {
   return text.length > TITLE_MAX ? `${text.slice(0, TITLE_MAX - 1).trimEnd()}…` : text;
 }
 
-function save({ id, cwd, model, theme, messages, context, startedAt, title }) {
+function save({ id, cwd, model, theme, allowAll, messages, context, startedAt, title }) {
   if (!id) return null;
   ensureDir();
   const now = new Date().toISOString();
@@ -63,6 +80,8 @@ function save({ id, cwd, model, theme, messages, context, startedAt, title }) {
     cwd: cwd || process.cwd(),
     model: model || null,
     theme: theme || null,
+    // "rodar tudo" e uma escolha da conversa: ao retomar, volta como estava.
+    allowAll: Boolean(allowAll),
     startedAt: startedAt || now,
     updatedAt: now,
     messages: list,
@@ -105,6 +124,7 @@ function list() {
       title: data.title || titleFrom(data.messages),
       cwd: data.cwd,
       model: data.model,
+      allowAll: Boolean(data.allowAll),
       updatedAt: data.updatedAt,
       messages: (data.messages || []).length,
     });
@@ -116,6 +136,20 @@ function latest() {
   return list()[0] || null;
 }
 
+/**
+ * Acha a conversa por id exato ou por prefixo unico: `kafox resume 3f1c`
+ * tambem funciona quando o codigo foi copiado pela metade.
+ */
+function find(value) {
+  const needle = normalizeId(value);
+  if (!needle) return null;
+  const exact = load(needle);
+  if (exact) return exact;
+  const matches = list().filter((chat) => chat.id.startsWith(needle));
+  if (matches.length !== 1) return null;
+  return load(matches[0].id);
+}
+
 function prune() {
   for (const chat of list().slice(MAX_SESSIONS)) {
     try {
@@ -130,9 +164,12 @@ module.exports = {
   chatsDir,
   newId,
   titleFrom,
+  normalizeId,
+  dayMonth,
   save,
   load,
   list,
   latest,
+  find,
   prune,
 };

package/src/theme.js

@@ -356,21 +356,16 @@ async function setContentBackground(url) {
       {
         type: "input",
         name: "url",
-        message: "Background image URL (PNG/JPG):",
+        message: "Imagem de fundo (arquivo ou URL PNG/JPG):",
         validate: (v) =>
-          /^https?:\/\/.+\.(png|jpg|jpeg|gif|webp)(\?.*)?$/i.test(v.trim()) ||
-          "Enter a valid image URL (http/https)",
+          Boolean(v.trim()) || "Informe o caminho do arquivo ou a URL",
       },
     ]);
     bg = answer.url.trim();
   }
   storage.setConfig({ background: bg });
-  console.log(chalk.green(`Background set: ${bg}`));
-  console.log(
-    chalk.dim(
-      "Tip: terminals like Windows Terminal / iTerm2 support image backgrounds. Use `kafox background` to open the modal."
-    )
-  );
+  console.log(chalk.green(`Fundo definido: ${bg}`));
+  console.log(chalk.dim("Abra a interface (kafox) para ver a imagem atras da conversa."));
 }
 
 module.exports = {

package/src/tools.js

@@ -1,6 +1,6 @@
 const fs = require("fs");
 const path = require("path");
-const { spawnSync } = require("child_process");
+const { spawn } = require("child_process");
 
 // Limites para nao estourar o contexto nem travar a TUI.
 const MAX_READ_CHARS = 40_000;
@@ -213,27 +213,94 @@ function listDir(cwd, args) {
   return `${relative(cwd, full)}\n${rows.join("\n")}${extra}`;
 }
 
+// Quanto de cada stream fica em memoria enquanto o comando roda. A saida
+// enviada ao modelo e menor (MAX_OUTPUT_CHARS), mas guardar um pouco mais
+// evita perder o comeco do stderr de um comando que fala muito.
+const MAX_COMMAND_BUFFER = 8 * 1024 * 1024;
+
+/**
+ * Executa o comando sem travar a TUI: `spawn` assincrono em vez de
+ * `spawnSync`, para o spinner e o relogio do cartao continuarem andando
+ * enquanto o processo roda.
+ */
 function runCommand(cwd, args) {
   const command = String(args.command || "").trim();
   if (!command) throw new Error("comando vazio");
   const timeout = Math.min(120_000, Math.max(1_000, Number(args.timeout_ms) || COMMAND_TIMEOUT_MS));
 
-  const result = spawnSync(command, {
-    shell: true,
-    cwd: path.resolve(cwd),
-    timeout,
-    encoding: "utf8",
-    maxBuffer: 8 * 1024 * 1024,
-    env: { ...process.env, KAFOX_CLI: "1" },
-  });
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(command, {
+        shell: true,
+        cwd: path.resolve(cwd),
+        env: { ...process.env, KAFOX_CLI: "1" },
+        windowsHide: true,
+      });
+    } catch (error) {
+      return resolve(`exit: ?\nstderr:\n${error.message}`);
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let spawnError = null;
+    let done = false;
 
-  const stdout = truncate(result.stdout || "", MAX_OUTPUT_CHARS);
-  const stderr = truncate(result.stderr || "", MAX_OUTPUT_CHARS);
-  const parts = [`exit: ${result.status == null ? "?" : result.status}`];
-  if (result.error?.code === "ETIMEDOUT") parts.push(`timeout: ${timeout}ms`);
-  if (stdout.trim()) parts.push(`stdout:\n${stdout.trimEnd()}`);
-  if (stderr.trim()) parts.push(`stderr:\n${stderr.trimEnd()}`);
-  return parts.join("\n");
+    // No Windows o `shell: true` cria um cmd.exe que nao leva o processo
+    // filho junto ao ser morto: taskkill /T encerra a arvore inteira.
+    const killTree = () => {
+      if (!child.pid) return;
+      if (process.platform === "win32") {
+        try {
+          const killer = spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+            windowsHide: true,
+            stdio: "ignore",
+          });
+          killer.on("error", () => {});
+        } catch {}
+        return;
+      }
+      try {
+        child.kill("SIGKILL");
+      } catch {}
+    };
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killTree();
+    }, timeout);
+    timer.unref?.();
+
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+      if (stdout.length < MAX_COMMAND_BUFFER) stdout += chunk;
+    });
+    child.stderr?.on("data", (chunk) => {
+      if (stderr.length < MAX_COMMAND_BUFFER) stderr += chunk;
+    });
+
+    const finish = (status) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      const out = truncate(stdout, MAX_OUTPUT_CHARS);
+      const err = truncate(stderr, MAX_OUTPUT_CHARS);
+      const parts = [`exit: ${status == null || spawnError ? "?" : status}`];
+      if (timedOut) parts.push(`timeout: ${timeout}ms`);
+      if (out.trim()) parts.push(`stdout:\n${out.trimEnd()}`);
+      if (err.trim()) parts.push(`stderr:\n${err.trimEnd()}`);
+      else if (spawnError) parts.push(`stderr:\n${spawnError}`);
+      resolve(parts.join("\n"));
+    };
+
+    child.on("error", (error) => {
+      spawnError = error.message;
+      finish(null);
+    });
+    child.on("close", (code) => finish(code));
+  });
 }
 
 async function executeTool(name, args = {}, context = {}) {

package/src/tui.js

@@ -24,6 +24,7 @@ const { diffBlocks } = require("./diff");
 const { toolMeta, parseCommandOutput } = require("./tools");
 const { McpHub } = require("./mcp");
 const sessions = require("./sessions");
+const wallpaper = require("./wallpaper");
 
 const ANSI = /\x1b\[[0-9;]*m/g;
 const stripAnsi = (value) => String(value).replace(ANSI, "");
@@ -510,6 +511,7 @@ function initialState() {
     pageSize: 10,
     mouse: true,
     retry: null,
+    wallpaper: null,
     sessionId: null,
     sessionStartedAt: null,
     model: cfg.model || null,
@@ -1168,11 +1170,13 @@ function buildOverlay(state, cols, rows) {
         if (themePicker) {
           line = padRight(` ${caret} ${padRight(item.id, 15)} ` + themeSwatch(item.id), width - 4);
         } else if (chatPicker) {
-          const when = String(item.updatedAt || "").slice(0, 10);
-          const right = chalk.dim(`${when} ${item.id}`);
+          // Formato do seletor: "titulo do chat - 28/10", com o codigo do
+          // resume discreto na direita para quem quiser copiar.
+          const right = chalk.dim(item.id);
           const space = width - 6;
-          const room = Math.max(12, space - visible(right) - 2);
-          const left = ` ${caret} ${truncate(item.title || item.id, room)}`;
+          const room = Math.max(12, space - visible(right) - 12);
+          const when = sessions.dayMonth(item.updatedAt);
+          const left = ` ${caret} ${truncate(item.title || item.id, room)}${when ? ` - ${when}` : ""}`;
           const gap = Math.max(1, space - visible(left) - visible(right));
           line = padRight(left + " ".repeat(gap) + right, width - 4);
         } else {
@@ -1333,6 +1337,9 @@ async function runTUI({
 
   // resume: "pick" abre o seletor de conversas, "last" pega a mais recente e
   // qualquer outro valor e o codigo do chat que o usuario fechou no Ctrl+C.
+  // `kafox --allow-all` (ou KAFOX_ALLOW_ALL=1) vale para a sessao inteira e
+  // ganha do que esta salvo na conversa.
+  const forcedAllow = Boolean(autoApprove) || process.env.KAFOX_ALLOW_ALL === "1";
   let resumeMissing = null;
   let resumePick = false;
   if (resume) {
@@ -1340,7 +1347,7 @@ async function runTUI({
       resumePick = true;
     } else {
       const id = resume === "last" || resume === true ? sessions.latest()?.id : String(resume);
-      const saved = sessions.load(id);
+      const saved = resume === "last" || resume === true ? sessions.load(id) : sessions.find(id);
       if (saved) {
         state.sessionId = saved.id;
         state.sessionStartedAt = saved.startedAt;
@@ -1348,6 +1355,7 @@ async function runTUI({
         state.context = Array.isArray(saved.context) ? saved.context : [];
         if (saved.model) state.model = saved.model;
         if (saved.theme) state.theme = saved.theme;
+        state.autoApprove = forcedAllow || Boolean(saved.allowAll);
         state.tokens = estimateTokens(state);
       } else {
         resumeMissing = String(id || resume);
@@ -1358,8 +1366,8 @@ async function runTUI({
     state.sessionId = sessions.newId();
     state.sessionStartedAt = new Date().toISOString();
   }
-  // `kafox --allow-all` (ou KAFOX_ALLOW_ALL=1) ja comeca sem pedir aprovacao.
-  state.autoApprove = Boolean(autoApprove) || process.env.KAFOX_ALLOW_ALL === "1";
+  // Sem conversa retomada, so a flag/env libera a aprovacao automatica.
+  if (forcedAllow) state.autoApprove = true;
   let mcp = new McpHub({ cwd: process.cwd() });
   let spinner = null;
   let escTimer = null;
@@ -1442,6 +1450,7 @@ async function runTUI({
         cwd: process.cwd(),
         model: state.model,
         theme: state.theme,
+        allowAll: state.autoApprove,
         messages: state.messages,
         context: state.context,
         startedAt: state.sessionStartedAt,
@@ -1456,9 +1465,51 @@ async function runTUI({
     const cols = Math.max(30, stdout.columns || 80);
     const rows = Math.max(14, stdout.rows || 24);
     const frame = buildFrame(state, cols, rows, commands);
+    const grid = wallpaperGrid(cols, rows);
+    if (grid) frame.lines = wallpaper.paint(frame.lines, grid);
     paintFrame(frame, { cols, rows });
   }
 
+  /**
+   * Grade da imagem no tamanho atual do terminal. Fica em cache: so e refeita
+   * quando a tela muda de tamanho ou quando o fundo troca.
+   */
+  function wallpaperGrid(cols, rows) {
+    const bg = state.wallpaper;
+    if (!bg?.image) return null;
+    if (!bg.grid || bg.cols !== cols || bg.rows !== rows) {
+      const base = wallpaper.hexToRgb(themeColors(state.theme).bg) || [12, 12, 16];
+      bg.grid = wallpaper.buildGrid(bg.image, cols, rows, { dim: 0.45, base });
+      bg.cols = cols;
+      bg.rows = rows;
+    }
+    return bg.grid;
+  }
+
+  /** `/background <arquivo|url>` desenha a foto atras da conversa. */
+  async function setBackground(source) {
+    const value = String(source || "").trim();
+    if (!value || ["off", "none", "0", "limpar"].includes(value.toLowerCase())) {
+      state.wallpaper = null;
+      state.modal = { title: "Fundo", text: "Imagem de fundo removida." };
+      storage.setConfig({ background: null });
+      return render();
+    }
+
+    state.modal = null;
+    state.wallpaper = { source: value, image: null, grid: null, cols: 0, rows: 0 };
+    render();
+    try {
+      const image = await wallpaper.load(value);
+      state.wallpaper = { source: value, image, grid: null, cols: 0, rows: 0 };
+      storage.setConfig({ background: value });
+    } catch (error) {
+      state.wallpaper = null;
+      state.modal = { title: "Fundo", text: `Nao consegui carregar ${value}.\n${error.message}` };
+    }
+    return render();
+  }
+
   /**
    * Desenho incremental: manda so as linhas diferentes, dentro de uma unica
    * atualizacao sincronizada. E o que impede o piscar do modal e do streaming.
@@ -1548,7 +1599,7 @@ async function runTUI({
 
   /** Troca a sessao atual pela conversa escolhida no seletor. */
   function resumeChat(id) {
-    const saved = sessions.load(id);
+    const saved = sessions.find(id);
     state.picker = null;
     if (!saved) {
       state.modal = { title: "Resume", text: "Nao consegui abrir essa conversa." };
@@ -1560,6 +1611,7 @@ async function runTUI({
     state.context = Array.isArray(saved.context) ? saved.context : [];
     if (saved.model) state.model = saved.model;
     if (saved.theme) state.theme = saved.theme;
+    state.autoApprove = forcedAllow || Boolean(saved.allowAll);
     state.files = [];
     state.tokens = estimateTokens(state);
     state.scroll = 0;
@@ -1645,9 +1697,25 @@ async function runTUI({
     // /models e /model sem argumento abrem o mesmo seletor navegavel.
     if ((name === "/model" || name === "/models") && !parts[1]) return openModelPicker();
     if (name === "/theme") return openThemePicker();
+    if (name === "/background" || name === "/bg") {
+      const value = parts.slice(1).join(" ");
+      if (!value) {
+        state.modal = {
+          title: "Fundo",
+          text:
+            "kafox /background <arquivo ou URL>\n\n" +
+            "Aceita PNG e JPG, de um arquivo do computador ou de um link https.\n" +
+            "Exemplo: /background ~/Imagens/ponte.jpg\n" +
+            "/background off remove a imagem.",
+        };
+        return render();
+      }
+      return setBackground(value);
+    }
     if (name === "/allow") {
       const argument = (parts[1] || "on").toLowerCase();
       state.autoApprove = argument !== "off" && argument !== "ask";
+      persist();
       state.modal = {
         title: "Aprovacao",
         text: state.autoApprove
@@ -1956,6 +2024,7 @@ async function runTUI({
     if (!pending) return;
     state.approval = null;
     if (decision === "always") state.autoApprove = true;
+    if (decision === "always") persist();
     render();
     pending.resolve(decision !== "deny");
   }
@@ -2275,6 +2344,8 @@ async function runTUI({
   render();
   if (resumePick) openChatPicker();
   connectMcp().catch(() => {});
+  const savedBackground = storage.getConfig().background;
+  if (savedBackground) setBackground(savedBackground).catch(() => {});
 
   spinner = setInterval(() => {
     if (!state.busy || closed) return;

package/src/wallpaper.js

@@ -0,0 +1,380 @@
+/**
+ * Imagem de fundo da TUI.
+ *
+ * O terminal nao tem "papel de parede": o jeito de mostrar uma foto e desenhar
+ * cada celula com dois pixels, um no primeiro plano e outro no fundo do caractere
+ * "▀" (meio bloco). Assim a imagem aparece atras do texto e o desenho continua
+ * legivel porque as cores sao escurecidas antes de entrar na tela.
+ *
+ * Suporta PNG (decodificado aqui, sem dependencia) e JPEG (jpeg-js), de um
+ * arquivo local ou de uma URL http(s).
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const zlib = require("zlib");
+
+const MAX_BYTES = 12 * 1024 * 1024;
+const FETCH_TIMEOUT_MS = 15_000;
+const HALF_BLOCK = "▀";
+
+/* ------------------------------------------------------------------ decoders */
+
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) return a;
+  return pb <= pc ? b : c;
+}
+
+/** PNG 8 bits (RGB, RGBA, tons de cinza e paleta), sem entrelacamento. */
+function decodePng(buffer) {
+  if (buffer.length < 8 || buffer.readUInt32BE(0) !== 0x89504e47) {
+    throw new Error("nao e um PNG valido");
+  }
+
+  let offset = 8;
+  let width = 0;
+  let height = 0;
+  let bitDepth = 8;
+  let colorType = 6;
+  let interlace = 0;
+  let palette = null;
+  const chunks = [];
+
+  while (offset + 8 <= buffer.length) {
+    const length = buffer.readUInt32BE(offset);
+    const type = buffer.toString("ascii", offset + 4, offset + 8);
+    const data = buffer.subarray(offset + 8, offset + 8 + length);
+    offset += 12 + length;
+
+    if (type === "IHDR") {
+      width = data.readUInt32BE(0);
+      height = data.readUInt32BE(4);
+      bitDepth = data[8];
+      colorType = data[9];
+      interlace = data[12];
+    } else if (type === "PLTE") {
+      palette = Buffer.from(data);
+    } else if (type === "IDAT") {
+      chunks.push(Buffer.from(data));
+    } else if (type === "IEND") {
+      break;
+    }
+  }
+
+  if (!width || !height) throw new Error("PNG sem cabecalho IHDR");
+  if (bitDepth !== 8) throw new Error(`PNG ${bitDepth} bits por canal nao suportado (use 8)`);
+  if (interlace) throw new Error("PNG entrelacado nao suportado");
+
+  const channels = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[colorType];
+  if (!channels) throw new Error(`tipo de cor PNG ${colorType} nao suportado`);
+  if (colorType === 3 && !palette) throw new Error("PNG com paleta mas sem PLTE");
+
+  const raw = zlib.inflateSync(Buffer.concat(chunks));
+  const stride = width * channels;
+  const lines = Buffer.alloc(stride * height);
+
+  let read = 0;
+  for (let y = 0; y < height; y += 1) {
+    if (read >= raw.length) throw new Error("PNG truncado");
+    const filter = raw[read];
+    read += 1;
+    const out = lines.subarray(y * stride, (y + 1) * stride);
+    const prev = y ? lines.subarray((y - 1) * stride, y * stride) : null;
+
+    for (let x = 0; x < stride; x += 1) {
+      const value = raw[read + x];
+      const left = x >= channels ? out[x - channels] : 0;
+      const up = prev ? prev[x] : 0;
+      const upLeft = prev && x >= channels ? prev[x - channels] : 0;
+      let byte;
+      switch (filter) {
+        case 0:
+          byte = value;
+          break;
+        case 1:
+          byte = value + left;
+          break;
+        case 2:
+          byte = value + up;
+          break;
+        case 3:
+          byte = value + ((left + up) >> 1);
+          break;
+        case 4:
+          byte = value + paeth(left, up, upLeft);
+          break;
+        default:
+          throw new Error(`filtro PNG ${filter} desconhecido`);
+      }
+      out[x] = byte & 0xff;
+    }
+    read += stride;
+  }
+
+  const pixels = new Uint8Array(width * height * 4);
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      const source = y * stride + x * channels;
+      const target = (y * width + x) * 4;
+      if (colorType === 0) {
+        const gray = lines[source];
+        pixels[target] = gray;
+        pixels[target + 1] = gray;
+        pixels[target + 2] = gray;
+        pixels[target + 3] = 255;
+      } else if (colorType === 4) {
+        const gray = lines[source];
+        pixels[target] = gray;
+        pixels[target + 1] = gray;
+        pixels[target + 2] = gray;
+        pixels[target + 3] = lines[source + 1];
+      } else if (colorType === 3) {
+        const index = lines[source] * 3;
+        pixels[target] = palette[index] ?? 0;
+        pixels[target + 1] = palette[index + 1] ?? 0;
+        pixels[target + 2] = palette[index + 2] ?? 0;
+        pixels[target + 3] = 255;
+      } else {
+        pixels[target] = lines[source];
+        pixels[target + 1] = lines[source + 1];
+        pixels[target + 2] = lines[source + 2];
+        pixels[target + 3] = colorType === 6 ? lines[source + 3] : 255;
+      }
+    }
+  }
+
+  return { width, height, pixels };
+}
+
+function decodeJpeg(buffer) {
+  // Carregado so quando alguem usa JPEG: quem nunca pediu fundo nao paga por ele.
+  let jpeg;
+  try {
+    jpeg = require("jpeg-js");
+  } catch {
+    throw new Error("JPEG precisa do pacote jpeg-js (npm i -g kafox-cli de novo)");
+  }
+  const image = jpeg.decode(Buffer.from(buffer), { useTArray: true, formatAsRGBA: true });
+  if (!image?.width) throw new Error("JPEG invalido");
+  return { width: image.width, height: image.height, pixels: image.data };
+}
+
+/** Descobre o formato pelos primeiros bytes e devolve RGBA. */
+function decodeBuffer(buffer) {
+  if (!buffer?.length) throw new Error("imagem vazia");
+  if (buffer.length < 12) throw new Error("arquivo pequeno demais para ser imagem");
+
+  const isPng = buffer.readUInt32BE(0) === 0x89504e47;
+  const isJpeg = buffer[0] === 0xff && buffer[1] === 0xd8;
+  if (isPng) return decodePng(buffer);
+  if (isJpeg) return decodeJpeg(buffer);
+
+  const head = buffer.toString("ascii", 0, 6);
+  if (head.startsWith("GIF")) throw new Error("GIF nao suportado: use PNG ou JPG");
+  if (head.startsWith("RIFF") && buffer.toString("ascii", 8, 12) === "WEBP") {
+    throw new Error("WebP nao suportado: use PNG ou JPG");
+  }
+  throw new Error("formato desconhecido: use PNG ou JPG");
+}
+
+/* ------------------------------------------------------------------ carregar */
+
+function expandHome(source) {
+  if (!source.startsWith("~")) return source;
+  return path.join(os.homedir(), source.slice(1));
+}
+
+async function readSource(source) {
+  const value = String(source || "").trim();
+  if (!value) throw new Error("informe o caminho ou a URL da imagem");
+
+  if (/^https?:\/\//i.test(value)) {
+    const response = await fetch(value, {
+      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      headers: { accept: "image/png,image/jpeg,image/*" },
+    });
+    if (!response.ok) throw new Error(`download falhou (HTTP ${response.status})`);
+    const size = Number(response.headers.get("content-length") || 0);
+    if (size > MAX_BYTES) throw new Error(`imagem grande demais (${Math.round(size / 1024 / 1024)} MB)`);
+    return Buffer.from(await response.arrayBuffer());
+  }
+
+  const file = path.resolve(expandHome(value));
+  const info = fs.statSync(file);
+  if (!info.isFile()) throw new Error(`${value} nao e um arquivo`);
+  if (info.size > MAX_BYTES) throw new Error(`imagem grande demais (${Math.round(info.size / 1024 / 1024)} MB)`);
+  return fs.readFileSync(file);
+}
+
+/** Carrega de URL ou arquivo e devolve a imagem em RGBA. */
+async function load(source) {
+  return decodeBuffer(await readSource(source));
+}
+
+/* ------------------------------------------------------------------ desenho */
+
+function hexToRgb(value) {
+  const hex = String(value || "").replace("#", "");
+  if (hex.length !== 6) return null;
+  const number = parseInt(hex, 16);
+  if (Number.isNaN(number)) return null;
+  return [(number >> 16) & 0xff, (number >> 8) & 0xff, number & 0xff];
+}
+
+/**
+ * Recorta o centro da imagem no formato da tela. Cada meia linha do terminal e
+ * um pixel quadrado, entao a proporcao alvo e `cols x rows*2`.
+ */
+function coverRegion(image, cols, rows) {
+  const target = cols / Math.max(1, rows * 2);
+  const current = image.width / image.height;
+  if (current > target) {
+    const width = image.height * target;
+    return { x: (image.width - width) / 2, y: 0, width, height: image.height };
+  }
+  const height = image.width / target;
+  return { x: 0, y: (image.height - height) / 2, width: image.width, height };
+}
+
+function averageColor(image, x0, y0, x1, y1, samples = 4) {
+  const { pixels, width } = image;
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  let count = 0;
+  const stepX = (x1 - x0) / samples;
+  const stepY = (y1 - y0) / samples;
+
+  for (let sy = 0; sy < samples; sy += 1) {
+    const py = Math.min(image.height - 1, Math.floor(y0 + sy * stepY));
+    for (let sx = 0; sx < samples; sx += 1) {
+      const px = Math.min(image.width - 1, Math.floor(x0 + sx * stepX));
+      const index = (py * width + px) * 4;
+      r += pixels[index];
+      g += pixels[index + 1];
+      b += pixels[index + 2];
+      count += 1;
+    }
+  }
+
+  if (!count) return [0, 0, 0];
+  return [Math.round(r / count), Math.round(g / count), Math.round(b / count)];
+}
+
+/**
+ * Monta a grade de celulas: cada celula tem dois pixels (topo e base do "▀").
+ * `dim` mistura a imagem com `base` para o texto continuar legivel.
+ */
+function buildGrid(image, cols, rows, { dim = 0.45, base = null } = {}) {
+  const columns = Math.max(1, Math.floor(cols));
+  const lines = Math.max(1, Math.floor(rows) * 2);
+  const region = coverRegion(image, columns, lines);
+  const back = base || [10, 10, 14];
+  const mix = (color) => color.map((value, index) => Math.round(value * dim + back[index] * (1 - dim)));
+
+  const cells = [];
+  for (let row = 0; row < lines; row += 1) {
+    const y0 = region.y + (row * region.height) / lines;
+    const y1 = region.y + ((row + 1) * region.height) / lines;
+    const line = [];
+    for (let col = 0; col < columns; col += 1) {
+      const x0 = region.x + (col * region.width) / columns;
+      const x1 = region.x + ((col + 1) * region.width) / columns;
+      line.push(mix(averageColor(image, x0, y0, x1, y1)));
+    }
+    cells.push(line);
+  }
+
+  // Junta as meias linhas em celulas com topo e base.
+  const grid = [];
+  for (let row = 0; row < lines; row += 2) {
+    const top = cells[row];
+    const bottom = cells[row + 1] || cells[row];
+    grid.push(top.map((color, col) => ({ top: color, bottom: bottom[col] })));
+  }
+  return { cols: columns, rows: Math.floor(rows), cells: grid };
+}
+
+/* ------------------------------------------------------------------ ANSI */
+
+/** Atualiza o estilo corrente a partir de uma sequencia SGR. */
+function trackStyle(sequence, style) {
+  const params = sequence.slice(2, -1);
+  const parts = params ? params.split(";") : ["0"];
+  if (parts.includes("0")) style.length = 0;
+  for (const part of parts) {
+    if (part === "0" || part === "39" || part === "49") continue;
+    style.push(part);
+  }
+}
+
+function backgroundActive(style) {
+  return style.some((part) => {
+    const code = Number(part);
+    return (code >= 40 && code <= 47) || (code >= 100 && code <= 107) || code === 48;
+  });
+}
+
+function cellEscape({ top, bottom }) {
+  return `\x1b[38;2;${top[0]};${top[1]};${top[2]}m\x1b[48;2;${bottom[0]};${bottom[1]};${bottom[2]}m`;
+}
+
+/**
+ * Troca os espacos vazios do frame pelas celulas da imagem. Texto e celulas com
+ * fundo proprio (caixas, paineis) ficam como estao.
+ */
+function paint(lines, grid) {
+  if (!grid?.cells?.length) return lines;
+
+  return lines.map((line, row) => {
+    const cells = grid.cells[row];
+    if (!cells) return line;
+    if (!line.includes(" ")) return line;
+
+    let out = "";
+    let col = 0;
+    let index = 0;
+    const style = [];
+
+    while (index < line.length) {
+      if (line[index] === "\x1b") {
+        const match = /^\x1b\[[0-9;]*m/.exec(line.slice(index));
+        if (match) {
+          out += match[0];
+          trackStyle(match[0], style);
+          index += match[0].length;
+          continue;
+        }
+      }
+
+      const char = line[index];
+      const cell = cells[col];
+      if (char === " " && cell && !backgroundActive(style)) {
+        const restore = style.length ? `\x1b[${style.join(";")}m` : "";
+        out += `\x1b[0m${cellEscape(cell)}${HALF_BLOCK}${restore}`;
+      } else {
+        out += char;
+      }
+      index += 1;
+      col += 1;
+    }
+
+    return out;
+  });
+}
+
+module.exports = {
+  load,
+  decodeBuffer,
+  decodePng,
+  buildGrid,
+  paint,
+  coverRegion,
+  hexToRgb,
+  HALF_BLOCK,
+  MAX_BYTES,
+};