sagadeck 1.5.0 → 1.7.0

package/src/ai/ia-config.js

@@ -0,0 +1,107 @@
+// A IA desta máquina: provedor, chave e modelos, num arquivo fora do código e fora da biblioteca
+// (~/.sagadeck/ia.json, ou SAGADECK_IA). Qualquer API compatível com a da OpenAI (OpenRouter, OpenAI, proxy da empresa);
+// a pessoa configura pela tela do Studio (IA › Configurar) ou à mão, sem mexer no código.
+//
+// Antes isso morava num programa à parte (o modelrelay, em Python, rodando na porta 8765). Na primeira vez, a
+// configuração dele (~/.modelrelay/config.toml) é trazida para cá, para ninguém perder a chave.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { renameRetry } from "../fs-retry.js";
+
+export const PROVIDERS = {
+  openrouter: { label: "OpenRouter", url: "https://openrouter.ai/api/v1", keyEnv: "OPENROUTER_API_KEY" },
+  openai: { label: "OpenAI", url: "https://api.openai.com/v1", keyEnv: "OPENAI_API_KEY" },
+};
+// Recomendação para começar, mostrada na tela Configurar IA. Serve também de teste da instalação: se nem com ela a IA
+// responde, o problema é o ambiente (rede, chave), não o modelo escolhido. Depois, cada um põe o modelo que quiser.
+export const RECOMMENDED = {
+  provider: "openrouter",
+  models: { text: "deepseek/deepseek-v4.1-flash", vision: "deepseek/deepseek-v4.1-flash", image: "google/gemini-3.1-flash-image", search: "deepseek/deepseek-v4.1-flash:online" },
+};
+// os papéis que o sagadeck usa; cada um aponta para um modelo do provedor
+export const ROLES = ["text", "vision", "image", "search"];
+
+export function iaFile(env = process.env, home = os.homedir()) {
+  return env.SAGADECK_IA || path.join(home, ".sagadeck", "ia.json");
+}
+
+const str = (v, max = 500) => (typeof v === "string" ? v.trim().slice(0, max) : "");
+
+// só os campos conhecidos, cada um no tipo certo (arquivo editado à mão não quebra o Studio)
+export function cleanIA(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const models = Object.fromEntries(ROLES.map((r) => [r, str(raw.models?.[r], 200)]).filter(([, v]) => v));
+  const headers = raw.headers && typeof raw.headers === "object"
+    ? Object.fromEntries(Object.entries(raw.headers).filter(([k, v]) => /^[\w-]+$/.test(k) && typeof v === "string").map(([k, v]) => [k, v.slice(0, 500)])) : {};
+  const out = { provider: str(raw.provider, 40), url: str(raw.url).replace(/\/+$/, ""), key: str(raw.key, 1000), keyEnv: str(raw.keyEnv, 100), models };
+  if (Object.keys(headers).length) out.headers = headers;
+  if (str(raw.adaptador)) out.adaptador = str(raw.adaptador);
+  return out.url || out.adaptador ? out : null;
+}
+
+export function loadIA(file = iaFile()) {
+  try { return cleanIA(JSON.parse(fs.readFileSync(file, "utf8"))); } catch { return null; }
+}
+
+// grava de forma atômica, só para quem é dono da conta (a chave mora aqui)
+export function saveIA(cfg, file = iaFile()) {
+  const clean = cleanIA(cfg);
+  if (!clean) throw new Error("Falta o endereço do provedor.");
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(clean, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  renameRetry(tmp, file);
+  return clean;
+}
+
+// a chave que vale: a do arquivo ou a da variável de ambiente indicada
+export function keyOf(cfg, env = process.env) {
+  return cfg?.key || (cfg?.keyEnv ? env[cfg.keyEnv] || "" : "");
+}
+
+// para mostrar na tela: a chave nunca sai inteira
+export function maskedIA(cfg, env = process.env) {
+  if (!cfg) return null;
+  const key = keyOf(cfg, env);
+  const { key: _k, ...rest } = cfg;
+  return { ...rest, keySet: !!key, keyHint: key ? `••••${key.slice(-4)}` : "", keyFrom: cfg.key ? "arquivo" : cfg.keyEnv && key ? "variável" : "" };
+}
+
+// ---- migração do modelrelay -------------------------------------------------------------------------------------
+// Só o pedaço de TOML que a tela do modelrelay escrevia: [seções], chave = "texto" e comentários.
+export function parseSimpleToml(text) {
+  const out = { "": {} };
+  let section = "";
+  for (const raw of String(text).split(/\r?\n/)) {
+    const line = raw.replace(/^\s+|\s+$/g, "");
+    if (!line || line.startsWith("#")) continue;
+    const sec = /^\[([^\]]+)\]$/.exec(line);
+    if (sec) { section = sec[1].trim(); out[section] ||= {}; continue; }
+    const kv = /^("?)([^"=]+?)\1\s*=\s*"((?:[^"\\]|\\.)*)"\s*(#.*)?$/.exec(line);
+    if (kv) out[section][kv[2].trim()] = kv[3].replace(/\\(["\\])/g, "$1");
+  }
+  return out;
+}
+
+// configuração do modelrelay → a desta máquina (provedor padrão, chave, modelos do sagadeck por cima dos gerais)
+export function fromModelrelay(toml) {
+  const t = parseSimpleToml(toml);
+  const name = t[""].provider || Object.keys(t).find((k) => k.startsWith("providers."))?.slice(10);
+  const p = (name && t[`providers.${name}`]) || {};
+  if (!p.base_url) return null;
+  const all = { ...(t.models || {}), ...(t["apps.sagadeck.models"] || {}) };
+  const models = Object.fromEntries(ROLES.filter((r) => all[r]).map((r) => [r, all[r]]));
+  return cleanIA({ provider: PROVIDERS[name] ? name : "outro", url: p.base_url, key: p.api_key || "", keyEnv: p.api_key_env || "", models });
+}
+
+// na primeira vez: sem ia.json e com o config.toml do modelrelay, traz a configuração (não sobrescreve nada)
+export function migrateModelrelay({ file = iaFile(), home = os.homedir(), env = process.env } = {}) {
+  if (fs.existsSync(file)) return null;
+  const toml = env.MODELRELAY_CONFIG || path.join(home, ".modelrelay", "config.toml");
+  let cfg;
+  try { cfg = fromModelrelay(fs.readFileSync(toml, "utf8")); } catch { return null; }
+  if (!cfg) return null;
+  saveIA(cfg, file);
+  return { from: toml, to: file };
+}

package/src/ai/llm.js

@@ -1,20 +1,23 @@
 import { mediaPrompt } from './art-direction.js';
 // sagadeck · Cliente de LLM (qualquer endpoint compatível com OpenAI: /v1/chat/completions)
 //
-// Por padrão fala com o `modelrelay serve` local (http://127.0.0.1:8765/v1), que decide pela
-// configuração dele para onde a chamada vai (OpenRouter, OpenAI, gateway corporativo...).
-// Também funciona apontando direto para um provedor.
+// Fala direto com o provedor configurado nesta máquina (~/.sagadeck/ia.json, tela Configurar IA do Studio:
+// src/ai/ia-config.js). As variáveis abaixo valem por cima da configuração:
 //
-//   SAGADECK_LLM_URL      base da API            (padrão: http://127.0.0.1:8765/v1)
-//   SAGADECK_LLM_KEY      bearer token opcional  (ex.: chave do OpenRouter se apontar direto)
-//   SAGADECK_TEXT_MODEL   modelo de texto        (padrão: "text"  — apelido no [models] do modelrelay)
-//   SAGADECK_IMAGE_MODEL  modelo de imagem       (padrão: "image" — idem)
-//   SAGADECK_VISION_MODEL modelo que vê imagens  (padrão: "vision" — quando o de texto não enxerga, a chamada com
-//                         imagem vai para ele em vez de perder a imagem; quem configura o relay decide qual é)
+//   SAGADECK_LLM_URL      base da API            (ex.: https://openrouter.ai/api/v1)
+//   SAGADECK_LLM_KEY      bearer token           (ex.: a chave do OpenRouter)
+//   SAGADECK_TEXT_MODEL   modelo de texto        (padrão: o "text" da configuração)
+//   SAGADECK_IMAGE_MODEL  modelo de imagem       (padrão: o "image" da configuração)
+//   SAGADECK_VISION_MODEL modelo que vê imagens  (padrão: o "vision" da configuração; quando o de texto não enxerga,
+//                         a chamada com imagem vai para ele em vez de perder a imagem)
+//   SAGADECK_SEARCH_MODEL modelo que busca na web (padrão: o "search" da configuração)
 //   SAGADECK_LLM_TIMEOUT  segundos por chamada; em streaming, segundos sem chegar nada (padrão: 180)
 //   SAGADECK_LLM_FIRST_TIMEOUT  em streaming, segundos até a 1ª palavra (o modelo pensa antes) (padrão: 600)
 
 import { currentUsage, recordUsage } from './usage.js';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { iaFile, loadIA, keyOf, migrateModelrelay } from './ia-config.js';
 import {setTimeout as delay} from 'node:timers/promises';
 
 export class LLMError extends Error {
@@ -28,35 +31,67 @@ export class LLMError extends Error {
   }
 }
 
+// De onde vem a IA: variáveis de ambiente (SAGADECK_LLM_URL…, valem por cima; é como os testes apontam para o LLM
+// falso) ou a configuração desta máquina (~/.sagadeck/ia.json, src/ai/ia-config.js). Os papéis text, vision, image e
+// search viram os modelos configurados; sem configuração nenhuma, a IA fica desligada (o Studio usa as regras locais).
+let migrated = false;
 export function llmConfig(env = process.env) {
+  const fromEnv = !!env.SAGADECK_LLM_URL;
+  if (!fromEnv && !migrated) { migrated = true; try { migrateModelrelay({ env, file: iaFile(env) }); } catch { /* segue sem */ } }
+  const ia = fromEnv ? null : loadIA(iaFile(env));
+  const m = ia?.models || {};
   return {
-    url: (env.SAGADECK_LLM_URL || "http://127.0.0.1:8765/v1").replace(/\/+$/, ""),
-    key: env.SAGADECK_LLM_KEY || "",
-    textModel: env.SAGADECK_TEXT_MODEL || "text",
-    imageModel: env.SAGADECK_IMAGE_MODEL || "image",
-    visionModel: env.SAGADECK_VISION_MODEL || "vision",
+    url: (env.SAGADECK_LLM_URL || ia?.url || "").replace(/\/+$/, ""),
+    key: env.SAGADECK_LLM_KEY || (ia ? keyOf(ia, env) : ""),
+    textModel: env.SAGADECK_TEXT_MODEL || m.text || "text",
+    imageModel: env.SAGADECK_IMAGE_MODEL || m.image || "image",
+    visionModel: env.SAGADECK_VISION_MODEL || m.vision || m.text || "vision",
+    // busca na web pelo modelo (no OpenRouter, um modelo ":online"); sem ele, a pesquisa usa os buscadores diretos
+    searchModel: env.SAGADECK_SEARCH_MODEL || m.search || (fromEnv ? "search" : ""),
+    headers: ia?.headers || {},
+    adaptador: ia?.adaptador || "",
+    source: fromEnv ? "variável" : ia ? "arquivo" : "nenhuma",
     timeoutMs: Number(env.SAGADECK_LLM_TIMEOUT || 180) * 1000,
     firstTimeoutMs: Number(env.SAGADECK_LLM_FIRST_TIMEOUT || 600) * 1000,
-    // o modelrelay escolhe os modelos deste app em [apps.sagadeck.models] (o resto vem de [models])
-    app: env.SAGADECK_APP || "sagadeck",
   };
 }
+export const llmConfigured = (cfg = llmConfig()) => !!(cfg.url || cfg.adaptador);
+
+// o papel (text, vision, image, search) vira o modelo configurado; outro nome passa como veio
+export function resolveModel(cfg, name) {
+  const roles = { text: cfg.textModel, vision: cfg.visionModel, image: cfg.imageModel, search: cfg.searchModel };
+  return roles[name] || name;
+}
 
 function headers(cfg) {
-  const h = { "Content-Type": "application/json", "X-Modelrelay-App": cfg.app || "sagadeck" };
+  const h = { "Content-Type": "application/json", ...(cfg.headers || {}) };
   if (cfg.key) h.Authorization = `Bearer ${cfg.key}`;
   return h;
 }
 
+// Adaptador (opcional, da pessoa): um .mjs cujo default é (url, init) => Response. Serve para o que não é compatível
+// com a API da OpenAI (outro jeito de autenticar, outro endereço) sem mexer no sagadeck. Sem ele, o fetch normal.
+const adapters = new Map();
+async function send(cfg, url, init) {
+  if (!cfg.adaptador) return fetch(url, init);
+  if (!adapters.has(cfg.adaptador)) adapters.set(cfg.adaptador, import(pathToFileURL(path.resolve(cfg.adaptador)).href).then((mod) => mod.default));
+  const fn = await adapters.get(cfg.adaptador);
+  if (typeof fn !== "function") throw new LLMError(`O adaptador ${cfg.adaptador} não exporta uma função padrão (url, init) => Response.`);
+  return fn(url, init);
+}
+const notConfigured = () => new LLMError("A IA não está configurada: no Studio, abra Configurar IA (ou crie ~/.sagadeck/ia.json).", { code: "AI_NOT_CONFIGURED" });
+const howToFix = "Confira o provedor e a chave em Configurar IA, no Studio.";
+
 // Disponibilidade com cache curto, para o Studio decidir entre LLM e as regras determinísticas.
 let availability = { at: 0, ok: false, url: "" };
 
 export async function llmAvailable({ force = false } = {}) {
   const cfg = llmConfig();
+  if (!llmConfigured(cfg)) return false;
   if (!force && availability.url === cfg.url && Date.now() - availability.at < 30_000) return availability.ok;
   let ok = false;
   try {
-    const res = await fetch(`${cfg.url}/models`, { headers: headers(cfg), signal: AbortSignal.timeout(2500) });
+    const res = await send(cfg, `${cfg.url}/models`, { headers: headers(cfg), signal: AbortSignal.timeout(2500) });
     ok = res.ok;
   } catch {
     ok = false;
@@ -106,13 +141,13 @@ export async function chat(messages, opts = {}) {
 
 async function chatUnmetered(messages, opts = {}) {
   const cfg = opts.cfg || llmConfig();
-  const key = `${cfg.url}|${cfg.app}|${opts.model || cfg.textModel}`;
+  const key = `${cfg.url}|${opts.model || cfg.textModel}`;
   // o modelo de texto não enxerga: a chamada com imagem vai para o modelo de visão (se o relay tiver um)
   const viaVision = async () => {
     const vision = cfg.visionModel;
-    if (!vision || vision === (opts.model || cfg.textModel) || noVision.has(`${cfg.url}|${cfg.app}|${vision}`)) return null;
+    if (!vision || vision === (opts.model || cfg.textModel) || noVision.has(`${cfg.url}|${vision}`)) return null;
     try { return { ...(await chatOnce(messages, { ...opts, model: vision, cfg })), visionRouted: vision }; }
-    catch (e) { if (refusesImages(e) || e.status === 400 || e.status === 404) { noVision.add(`${cfg.url}|${cfg.app}|${vision}`); return null; } throw e; }
+    catch (e) { if (refusesImages(e) || e.status === 400 || e.status === 404) { noVision.add(`${cfg.url}|${vision}`); return null; } throw e; }
   };
   if (hasImageParts(messages) && noVision.has(key)) {
     return (await viaVision()) || { ...(await chatOnce(withoutImages(messages), { ...opts, cfg })), imagesDropped: true };
@@ -147,7 +182,8 @@ async function chatOnce(messages, opts = {}) {
 }
 
 async function chatOnceRaw(messages, { model, temperature, maxTokens, onDelta, signal, reasoningOff, cfg = llmConfig() } = {}) {
-  const body = { model: model || cfg.textModel, messages };
+  if (!llmConfigured(cfg)) throw notConfigured();
+  const body = { model: resolveModel(cfg, model || cfg.textModel), messages };
   if (reasoningOff) body.reasoning = { enabled: false };
   if (temperature !== undefined) body.temperature = temperature;
   if (maxTokens) body.max_tokens = maxTokens;
@@ -155,7 +191,7 @@ async function chatOnceRaw(messages, { model, temperature, maxTokens, onDelta, s
 
   let res;
   try {
-    res = await fetch(`${cfg.url}/chat/completions`, {
+    res = await send(cfg, `${cfg.url}/chat/completions`, {
       method: "POST",
       headers: headers(cfg),
       body: JSON.stringify(body),
@@ -168,7 +204,7 @@ async function chatOnceRaw(messages, { model, temperature, maxTokens, onDelta, s
     if (e.cause?.code === "UND_ERR_HEADERS_TIMEOUT") return chatStream(body, () => {}, cfg, signal);
     const why = e.name === "TimeoutError" ? `sem resposta em ${cfg.timeoutMs / 1000}s` : e.message;
     throw new LLMError(`Não consegui falar com o LLM em ${cfg.url} (${why}). ` +
-      "Rode `modelrelay serve` ou ajuste SAGADECK_LLM_URL.", { cause: e });
+      howToFix, { cause: e });
   }
 
   const raw = await res.text();
@@ -213,7 +249,7 @@ async function chatStream(body, onDelta, cfg, signal) {
 async function readStream(body, onDelta, cfg, signal, sig, alive, wrote = () => {}, noTextFor = () => 0) {
   let res;
   try {
-    res = await fetch(`${cfg.url}/chat/completions`, {
+    res = await send(cfg, `${cfg.url}/chat/completions`, {
       method: "POST",
       headers: headers(cfg),
       body: JSON.stringify({ ...body, stream: true, stream_options: { include_usage: true } }),
@@ -223,7 +259,7 @@ async function readStream(body, onDelta, cfg, signal, sig, alive, wrote = () =>
     if (signal?.aborted) throw new LLMError("Parado a pedido.", { cause: e, aborted: true });
     const why = e.name === "TimeoutError" ? `não começou a responder em ${(cfg.firstTimeoutMs ?? cfg.timeoutMs) / 1000} s` : e.message;
     throw new LLMError(`Não consegui falar com o LLM em ${cfg.url} (${why}). ` +
-      "Rode `modelrelay serve` ou ajuste SAGADECK_LLM_URL.", { cause: e });
+      howToFix, { cause: e });
   }
   alive(); // começou: daqui em diante, o limite é ficar sem chegar nada
   if (!res.ok) {

package/src/api-client.js

@@ -25,6 +25,7 @@ import { connectWs } from "./ws.js";
 import { protect, unprotect, unprotectAll, PROTECTION } from "./protect.js";
 
 const C = globalThis.SagadeckApiCore;
+const BEARER = "Bearer {{secret.token}}"; // o "token fixo" do formulário: cabeçalho em todo pedido do ambiente
 
 // As variáveis e segredos dos slides de API moram FORA das apresentações: ~/.sagadeck/ambientes.yaml (no Windows,
 // C:\Users\<você>\.sagadeck\ambientes.yaml) ou SAGADECK_AMBIENTES. Mandar um deck para alguém nunca leva segredo
@@ -128,7 +129,7 @@ export class ApiEnvironments {
     catch (e) { throw new ApiError(`${this.file}: YAML inválido: ${e.message}`, "config"); }
     const envs = data.environments && typeof data.environments === "object" ? data.environments : {};
     // segredos cifrados (dpapi:…): decifra todos de uma vez (um PowerShell só)
-    try { unprotectAll(Object.values(envs).flatMap((e) => Object.values((e && e.secrets) || {}))); }
+    try { unprotectAll(Object.values(envs).flatMap((e) => [...Object.values((e && e.secrets) || {}), e?.token?.client_secret].filter((v) => typeof v === "string"))); }
     catch (e) { throw new ApiError(`${this.file}: ${e.message}`, "config"); }
     return { current: data.current || null, environments: envs };
   }
@@ -236,6 +237,106 @@ export class ApiEnvironments {
     return this.state();
   }
 
+  // ---- tela Ambientes por campos (src/studio/public/api-envs-form.js) ----------------------------------------------
+  // O mesmo arquivo, visto como formulário: endereço base, variáveis, segredos (só o nome e de onde vêm; o valor nunca
+  // sai) e a autenticação (nenhuma, token fixo ou token que expira). O que o formulário não conhece (ca, insecure,
+  // outros cabeçalhos) fica no arquivo como estava.
+  formState() {
+    const raw = fs.existsSync(this.file) ? (YAML.parse(fs.readFileSync(this.file, "utf8")) || {}) : {};
+    const envs = raw.environments && typeof raw.environments === "object" ? raw.environments : {};
+    return {
+      file: this.file, exists: fs.existsSync(this.file), protection: PROTECTION, current: raw.current || null,
+      builtin: Object.keys(this.builtin),
+      envs: Object.entries(envs).map(([name, e = {}]) => {
+        const bearer = e.headers?.Authorization === BEARER;
+        const auth = e.token?.url ? { type: "token", url: e.token.url, client_id: e.token.client_id || "", field: e.token.field || "", secretEnv: e.token.client_secret_env || "", secretSet: e.token.client_secret != null }
+          : bearer ? { type: "bearer", secretEnv: typeof e.secrets?.token === "object" ? e.secrets.token.env || "" : "", secretSet: typeof e.secrets?.token === "string" }
+          : { type: "nenhuma" };
+        const otherHeaders = Object.keys(e.headers || {}).filter((h) => !(bearer && h === "Authorization"));
+        return {
+          name, base: e.vars?.base != null ? String(e.vars.base) : "",
+          vars: Object.entries(e.vars || {}).filter(([k]) => k !== "base").map(([k, v]) => ({ name: k, value: String(v) })),
+          secrets: Object.entries(e.secrets || {}).filter(([k]) => !(bearer && k === "token")).map(([k, v]) => ({ name: k, env: typeof v === "object" && v ? v.env || "" : "", set: typeof v === "string" })),
+          auth, advanced: !!(e.ca || e.insecure || otherHeaders.length),
+        };
+      }),
+    };
+  }
+
+  saveForm(list, { current } = {}) {
+    if (!Array.isArray(list)) throw new ApiError("Mande a lista de ambientes.", "config");
+    const NAME = /^[A-Za-z0-9_-]{1,40}$/, VAR = /^[A-Za-z_][A-Za-z0-9_]*$/;
+    const seen = new Set();
+    for (const f of list) {
+      if (!NAME.test(String(f?.name || ""))) throw new ApiError(`Nome de ambiente inválido: "${f?.name || ""}". Use letras, números, - e _ (ex.: dev, hom, prod).`, "config");
+      if (seen.has(f.name)) throw new ApiError(`O ambiente "${f.name}" aparece duas vezes.`, "config");
+      seen.add(f.name);
+      if (f.base && !/^https?:\/\//i.test(f.base)) throw new ApiError(`Ambiente "${f.name}": o endereço base começa com http:// ou https://.`, "config");
+      for (const v of [...(f.vars || []), ...(f.secrets || [])]) if (!VAR.test(String(v?.name || ""))) throw new ApiError(`Ambiente "${f.name}": nome inválido "${v?.name || ""}". Use letras, números e _ (ex.: path_id).`, "config");
+      if (f.auth?.type === "token" && !/^https?:\/\//i.test(f.auth.url || "")) throw new ApiError(`Ambiente "${f.name}": falta o endereço do token (https://…).`, "config");
+    }
+    this.editFile((doc) => {
+      const old = doc.toJS()?.environments || {};
+      for (const name of Object.keys(old)) if (!seen.has(name)) doc.deleteIn(["environments", name]);
+      for (const f of list) {
+        const at = (...k) => ["environments", f.name, ...k];
+        const prev = old[f.name] || {};
+        if (!doc.hasIn(at())) doc.setIn(at(), doc.createNode({}));
+        // variáveis: base + as da tabela; a que saiu da tabela sai do arquivo
+        const vars = { ...(f.base ? { base: f.base } : {}), ...Object.fromEntries((f.vars || []).map((v) => [v.name, String(v.value ?? "")])) };
+        for (const k of Object.keys(prev.vars || {})) if (!(k in vars)) doc.deleteIn(at("vars", k));
+        for (const [k, v] of Object.entries(vars)) doc.setIn(at("vars", k), v);
+        // segredos: valor novo (cifrado), variável de ambiente, ou fica o que já estava
+        const keepToken = f.auth?.type === "bearer";
+        const wanted = new Set([...(f.secrets || []).map((x) => x.name), ...(keepToken ? ["token"] : [])]);
+        for (const k of Object.keys(prev.secrets || {})) if (!wanted.has(k)) doc.deleteIn(at("secrets", k));
+        const putSecret = (name, { value, env } = {}) => {
+          if (env) doc.setIn(at("secrets", name), doc.createNode({ env }));
+          else if (value) doc.setIn(at("secrets", name), protect(String(value)));
+          else if (!doc.hasIn(at("secrets", name))) throw new ApiError(`Ambiente "${f.name}": falta o valor do segredo "${name}".`, "config");
+        };
+        for (const x of f.secrets || []) putSecret(x.name, x);
+        // autenticação
+        const ourBearer = doc.getIn(at("headers", "Authorization")) === BEARER;
+        if (f.auth?.type === "bearer") {
+          putSecret("token", { value: f.auth.value, env: f.auth.secretEnv });
+          doc.setIn(at("headers", "Authorization"), BEARER);
+        } else if (ourBearer) doc.deleteIn(at("headers", "Authorization"));
+        if (doc.getIn(at("headers")) && !Object.keys(doc.getIn(at("headers")).toJSON?.() || {}).length) doc.deleteIn(at("headers"));
+        if (f.auth?.type === "token") {
+          const t = { url: f.auth.url, ...(f.auth.client_id ? { client_id: f.auth.client_id } : {}), ...(f.auth.field ? { field: f.auth.field } : {}) };
+          for (const k of ["url", "client_id", "field"]) if (!(k in t)) doc.deleteIn(at("token", k)); else doc.setIn(at("token", k), t[k]);
+          if (f.auth.secretEnv) { doc.setIn(at("token", "client_secret_env"), f.auth.secretEnv); doc.deleteIn(at("token", "client_secret")); }
+          else if (f.auth.value) { doc.setIn(at("token", "client_secret"), protect(String(f.auth.value))); doc.deleteIn(at("token", "client_secret_env")); }
+          else if (!doc.hasIn(at("token", "client_secret")) && !doc.hasIn(at("token", "client_secret_env"))) throw new ApiError(`Ambiente "${f.name}": falta o segredo do token (client secret).`, "config");
+        } else if (doc.hasIn(at("token"))) doc.deleteIn(at("token"));
+      }
+      const names = list.map((f) => f.name);
+      doc.set("current", names.includes(current) ? current : names[0] || null);
+    });
+    this.tokens.clear();
+    return this.formState();
+  }
+
+  // Testar um ambiente salvo: o endereço base responde? o token sai? (só diz o que aconteceu; nada vai para a tela)
+  async check(name) {
+    const env = this.env(name);
+    const out = { name: env.name };
+    const base = env.vars?.base;
+    if (base) {
+      try {
+        const res = await open({ method: "GET", url: String(base), headers: { Accept: "*/*", ...C.render(env.headers || {}, this.secretVars(env)) }, ca: this.ca(env), insecure: !!env.insecure, timeout: 10000 });
+        res.resume();
+        out.base = { ok: true, status: res.statusCode };
+      } catch (e) { out.base = { ok: false, error: this.maskText(env, e.message) }; }
+    }
+    if (env.token?.url) {
+      try { const v = await this.token(env, { renew: true }); out.token = { ok: true, last4: v.slice(-4) }; }
+      catch (e) { out.token = { ok: false, error: this.maskText(env, e.message) }; }
+    }
+    return out;
+  }
+
   env(name) {
     const data = this.load();
     const n = name || this.currentName(data);
@@ -257,7 +358,7 @@ export class ApiEnvironments {
 
   secrets(env) {
     const t = env.token || {};
-    const out = [this.tokens.get(env.name)?.value, t.client_secret, t.client_secret_env && process.env[t.client_secret_env], ...Object.values(env.headers || {}), ...Object.values(this.secretVars(env))];
+    const out = [this.tokens.get(env.name)?.value, t.client_secret != null ? unprotect(t.client_secret) : null, t.client_secret_env && process.env[t.client_secret_env], ...Object.values(env.headers || {}), ...Object.values(this.secretVars(env))];
     return out.filter((s) => typeof s === "string" && s.length >= 6);
   }
 
@@ -273,7 +374,7 @@ export class ApiEnvironments {
     const cached = this.tokens.get(env.name);
     if (!renew && cached && Date.now() < cached.renewAt) return cached.value;
     const id = t.client_id ?? (t.client_id_env && process.env[t.client_id_env]);
-    const secret = t.client_secret ?? (t.client_secret_env && process.env[t.client_secret_env]);
+    const secret = (t.client_secret != null ? unprotect(t.client_secret) : null) ?? (t.client_secret_env && process.env[t.client_secret_env]);
     if (!id || !secret) throw new ApiError(`Ambiente "${env.name}": falta client_id/client_secret do token (ou a variável ${t.client_secret_env || t.client_id_env || "…"})`, "config");
     const fields = { [t.id_field || "client_id"]: id, [t.secret_field || "client_secret"]: secret, ...(t.extra || {}) };
     const form = t.format === "form";
@@ -320,7 +421,7 @@ export class ApiEnvironments {
       throw new ApiError(`Ambiente "${env.name}" não tem ${names.join(", ")} configurado em secrets:`, "config");
     }
     req = { ...req, url: C.render(req.url, sv), headers: C.render(req.headers || {}, sv), body: C.render(req.body, sv) };
-    const headers = { Accept: "application/json, text/event-stream, */*", ...(env.headers || {}), ...(req.headers || {}) };
+    const headers = { Accept: "application/json, text/event-stream, */*", ...C.render(env.headers || {}, sv), ...(req.headers || {}) };
     let body = req.body;
     const file = req.file || null; // { name, type, data: Buffer } — o arquivo do slide (upload ou base64)
     const needsFile = (req.form && Object.values(req.form).includes("@file")) || /\{\{\s*file\./.test(JSON.stringify(body ?? ""));
@@ -488,7 +589,7 @@ export class ApiEnvironments {
     const sv = this.secretVars(env);
     let url = C.render(String(rt.url || ""), { ...(env.vars || {}), ...sv });
     const t = env.token || {};
-    const headers = { ...(env.headers || {}) };
+    const headers = { ...C.render(env.headers || {}, sv) };
     const auth = String(rt.auth || "header");
     if (auth !== "none") {
       const tok = await this.token(env);

package/src/library.js

@@ -22,8 +22,9 @@ import YAML from "yaml";
 import * as MASTER from "./master.js";
 import { unpackDeck } from "./package.js";
 import { writeDeckFile } from "./deck-file.js";
+import { loadPreferences } from "./preferences.js";
 
-export const TRASH_DAYS = 1;
+export const TRASH_DAYS = 30; // padrão; cada máquina escolhe em Preferências › Biblioteca (lixeiraDias)
 const TRASH = ".lixeira";
 const TOPIC_META = ".topico.json";
 const COLORS = ["#d33a2c", "#0f6cbd", "#e5a50a", "#8b5cf6", "#0e9f6e", "#e8590c", "#d6336c", "#495057"];
@@ -128,7 +129,9 @@ function uniquePath(dir, name, ext = "") {
   return p;
 }
 
-export function openLibrary(root) {
+// trashDays: quantos dias a lixeira guarda (padrão: o das Preferências desta máquina, lido a cada limpeza)
+export function openLibrary(root, { trashDays } = {}) {
+  const keepDays = () => trashDays ?? loadPreferences().biblioteca?.lixeiraDias ?? TRASH_DAYS;
   root = path.resolve(root);
   fs.mkdirSync(root, { recursive: true });
 
@@ -191,7 +194,7 @@ export function openLibrary(root) {
       topics.push({ id: e.name, name: e.name, color: meta.color || COLORS[topics.length % COLORS.length], count: mine.length, created: meta.created || 0 });
     }
     topics.sort((a, b) => a.name.localeCompare(b.name, "pt-BR"));
-    return { root, topics, decks, trash: listTrash() };
+    return { root, topics, decks, trash: listTrash(), trashDays: keepDays() };
   }
 
   // ---- tópicos ----
@@ -414,7 +417,8 @@ export function openLibrary(root) {
     return all.length;
   }
   function purgeOld(now = Date.now()) {
-    for (const t of listTrash()) if (now - t.deleted > TRASH_DAYS * 864e5) purgeDeck(t.id);
+    const days = keepDays();
+    for (const t of listTrash()) if (now - t.deleted > days * 864e5) purgeDeck(t.id);
   }
 
   // ---- importar .sagadeck / .zip ----

package/src/motion.js

@@ -22,11 +22,11 @@ function drawTrace(ctx,o,t,w,h){
  ctx.restore();
 }
 function scene(o){
- let active=o.type!=='chat',started=false,epoch=performance.now(),serial=0,phase='idle',elapsed=0,previous=0;let reduced=!!o.still||matchMedia('(prefers-reduced-motion:reduce)').matches;const main=document.querySelector('main'),canvas=document.querySelector('canvas'),ctx=canvas.getContext('2d');
+ let active=o.type!=='chat',started=false,epoch=performance.now(),serial=0,phase='idle',elapsed=0,previous=0;const reduceQuery=matchMedia('(prefers-reduced-motion:reduce)');let still=false,reduced=!!o.still||reduceQuery.matches;const recompute=()=>{reduced=!!o.still||still||reduceQuery.matches;};reduceQuery.addEventListener?.('change',recompute);const main=document.querySelector('main'),canvas=document.querySelector('canvas'),ctx=canvas.getContext('2d');
  const message=(kind)=>parent.postMessage({sagaMotion:kind},'*');
  const chat=document.querySelector('.chat'),input=document.querySelector('.input'),thread=document.querySelector('.thread'),status=document.querySelector('.status');
  function reset(){started=false;phase='idle';elapsed=0;chat.hidden=true;input.textContent='';thread.replaceChildren();status.textContent='';}
- message('ready');window.addEventListener('message',e=>{if(e.source!==parent)return;if(e.data?.sagaMotion==='poster'){reduced=true;if(o.type==='terminal')document.querySelector('.feed').textContent=o.lines.join('\n');}if(e.data?.sagaMotion==='active')active=!!e.data.active;if(e.data?.sagaMotion==='reset')reset();if(e.data?.sagaMotion==='start'){reset();started=true;active=true;phase='recognize';chat.hidden=false;}});
+ window.__sagaMotion=()=>({active,reduced,started,serial,phase});message('ready');window.addEventListener('message',e=>{if(e.source!==parent)return;if(e.data?.sagaMotion==='poster'){still=e.data.active!==false;recompute();if(reduced&&o.type==='terminal')document.querySelector('.feed').textContent=o.lines.join('\n');}if(e.data?.sagaMotion==='active')active=!!e.data.active;if(e.data?.sagaMotion==='reset')reset();if(e.data?.sagaMotion==='start'){reset();started=true;active=true;phase='recognize';chat.hidden=false;}});
  if(o.type==='chat'&&o.manual){const request=e=>{if(!active)return;if(e.type==='keydown'&&![' ','Enter','ArrowRight','PageDown'].includes(e.key))return;e.preventDefault();message('start-request');};document.addEventListener('click',request);document.addEventListener('keydown',request);}
  if(o.type==='chat'&&!o.manual){started=true;phase='recognize';chat.hidden=false;}
  function bubble(text,kind){const el=document.createElement('div');el.className='bubble '+kind;el.textContent=text;thread.append(el);return el;}

package/src/preferences.js

@@ -22,6 +22,9 @@ export const PREF_SCHEMA = {
   exportacao: {
     pdfClaro: { def: false },   // PDF e impressão na versão clara do tema (quando o tema tem par claro/escuro)
   },
+  biblioteca: {
+    lixeiraDias: { def: 30, min: 1, max: 365 }, // excluída fica restaurável por tantos dias, depois é apagada de vez
+  },
 };
 
 export function preferencesFile(env = process.env, home = os.homedir()) {

package/src/research/research.js

@@ -11,7 +11,7 @@
 // (fontes.json, notas.md e o texto de cada fonte). Sem internet (a rede do banco): avisa e segue sem inventar.
 import fs from "node:fs";
 import path from "node:path";
-import { chat } from "../ai/llm.js";
+import { chat, llmConfig } from "../ai/llm.js";
 import { fetchUrlDoc } from "../ai/context.js";
 import { searchDuckDuckGo } from "./duckduckgo.js";
 import { searchWikipedia } from "./wikipedia.js";
@@ -66,11 +66,12 @@ export async function arxivSearch(q, { limit = 5 } = {}) {
     return { title: tag("title"), url: abs, pdf: abs.replace("/abs/", "/pdf/"), snippet: clip(tag("summary"), 300), date: tag("published").slice(0, 10), arxiv: true };
   });
 }
-// Busca pelo modelo "search" do modelrelay (no OpenRouter, um modelo com ":online": a busca na web dele, por API
-// oficial). O DuckDuckGo direto passou a responder com desafio anti-robô; ele fica como segunda tentativa. Sem o
-// apelido "search" no modelrelay (a rede do banco), não há buscador: a pesquisa avisa e segue sem inventar.
+// Busca pelo modelo de busca configurado (Configurar IA › busca; no OpenRouter, um modelo com ":online": a busca na
+// web dele, por API oficial). O DuckDuckGo direto passou a responder com desafio anti-robô; ele fica como segunda
+// tentativa. Sem modelo de busca (a rede do banco), não há buscador: a pesquisa avisa e segue sem inventar.
 export async function llmSearch(q, { limit = 8 } = {}) {
-  const model = process.env.SAGADECK_SEARCH_MODEL || "search";
+  const model = llmConfig().searchModel;
+  if (!model) throw new Error("sem modelo de busca configurado");
   const r = await chat([{ role: "user", content: `Hoje é ${today()}. Pesquise na web e liste as ${limit} melhores fontes para: ${q}\nPrefira fontes primárias (site oficial, documentação, artigo, imprensa séria); para humor, memes e opiniões sobre cultura, blogs e fóruns também podem ser pertinentes. Para cada uma, o título, a URL completa e exata (a página, não o site), uma frase do que ela traz e a data, se houver.\nResponda só JSON: [{"title": "…", "url": "https://…", "snippet": "…", "date": "…"}]` }], { model, maxTokens: 3000, temperature: 0, reasoningOff: true });
   const t = r.text || "", m = t.match(/```(?:json)?\s*([\s\S]*?)```/), raw = m ? m[1] : t.slice(t.indexOf("["), t.lastIndexOf("]") + 1);
   return (JSON.parse(raw) || []).filter((x) => /^https?:\/\//.test(x?.url || "")).slice(0, limit).map((x) => ({ title: String(x.title || x.url), url: String(x.url), snippet: String(x.snippet || ""), date: String(x.date || "") }));

package/src/runtime/motion.js

@@ -10,6 +10,10 @@ for(const frame of document.querySelectorAll('iframe[data-motion]')){
   document.addEventListener('keydown',begin,true);slide.addEventListener('click',begin,true);
  }
  window.addEventListener('message',e=>{if(e.source!==frame.contentWindow)return;if(e.data?.sagaMotion==='done')finish();if(e.data?.sagaMotion==='ready')activate();if(e.data?.sagaMotion==='start-request'&&slide?.classList.contains('current')&&!done){if(started)finish();else{started=true;send('start');}}});
- const activate=()=>{const active=slide?.classList.contains('current');send('active',active);if(document.documentElement.classList.contains('export')||document.documentElement.dataset.motion==='none'||matchMedia('(prefers-reduced-motion: reduce)').matches)send('poster');if(!active){started=false;done=false;frame.style.visibility='';send('reset');}};
+ const activate=()=>{const active=slide?.classList.contains('current');send('active',active);send('poster',document.documentElement.classList.contains('export')||document.documentElement.dataset.motion==='none'||matchMedia('(prefers-reduced-motion: reduce)').matches);if(!active){started=false;done=false;frame.style.visibility='';send('reset');}};
  frame.addEventListener('load',activate);if(slide)new MutationObserver(activate).observe(slide,{attributes:true,attributeFilter:['class']});
+ // a cena pode ter carregado e dito 'ready' antes deste script escutar: fala com ela já (senão ela não sabe do slide
+ // atual nem do movimento reduzido e anima sem parar)
+ activate();
+ matchMedia('(prefers-reduced-motion: reduce)').addEventListener?.('change',activate);
 }

package/src/studio/ai-chat-route.js

@@ -119,7 +119,7 @@ _${c.naoConfirmados.length} observação(ões) descartada(s): o trecho citado n
         // Sem modelo, ninguém decide nada: nem "o que é X?" nem "resuma" viram edição por palavra-chave
         // (as regras antigas trocavam o layout e enfiavam texto genérico no slide). O deck fica como está.
         return {
-          reply: `A IA está desligada (nenhum LLM respondendo em ${llmConfig().url}), então não mexi em nada. Rode "modelrelay serve" ou defina SAGADECK_LLM_URL e mande de novo.`,
+          reply: `A IA está desligada (${llmConfig().url ? `nenhum LLM respondendo em ${llmConfig().url}` : "não configurada"}), então não mexi em nada. Configure em Configurar IA (provedor e chave) e mande de novo.`,
           spec, actions: [], targetSlide: body.targetSlide, talk: true, mode: "off",
         };
       }

package/src/studio/api-routes.js

@@ -54,10 +54,21 @@ export async function apiRoutes({ req, res, pathname, url, W, apiEnv, rtSessions
     const exists = fs.existsSync(apiEnv.file);
     return reply(200, { file: apiEnv.file, exists, text: exists ? fs.readFileSync(apiEnv.file, "utf8") : AMBIENTES_MODELO, builtin: Object.keys(apiEnv.builtin) });
   }
+  // tela Ambientes por campos: o mesmo arquivo como formulário (o valor de segredo nunca vem)
+  if (pathname === "/api/http/ambientes/form" && req.method === "GET") {
+    try { return reply(200, apiEnv.formState()); } catch (e) { return reply(400, { error: `${apiEnv.file}: ${e.message}` }); }
+  }
   if (req.method !== "POST") return reply(405, { error: "use POST" });
   if (!/^application\/json/i.test(req.headers["content-type"] || "")) return reply(415, { error: "envie JSON" });
   let body;
   try { body = await readJSON(req); } catch (e) { return reply(400, { error: e.message }); }
+  if (pathname === "/api/http/ambientes/form") {
+    if (fs.existsSync(apiEnv.file)) { fs.copyFileSync(apiEnv.file, `${apiEnv.file}.bak`); fs.chmodSync(`${apiEnv.file}.bak`, 0o600); }
+    try { return reply(200, apiEnv.saveForm(body.envs, { current: body.current })); } catch (e) { return reply(400, { error: e.message }); }
+  }
+  if (pathname === "/api/http/ambientes/testar") {
+    try { return reply(200, await apiEnv.check(String(body.name || ""))); } catch (e) { return reply(400, { error: e.message }); }
+  }
   if (pathname === "/api/http/ambientes" || pathname === "/api/http/ambientes/validar") {
     const text = String(body.text ?? "");
     let data;

package/src/studio/banner.js

@@ -0,0 +1,18 @@
+// O que o `sagadeck studio` escreve ao subir. A primeira linha é o endereço do Studio, a página que a pessoa abre: antes
+// vinha primeiro o endereço de um serviço de IA à parte, e um agente pedido para "deixar pronto para usar" abria a
+// página dele ou, sem achar o Studio, saía criando uma interface do zero. A IA se configura dentro do Studio.
+import { PROVIDERS } from "../ai/ia-config.js";
+
+const providerName = (ai) => Object.values(PROVIDERS).find((p) => p.url === ai.url)?.label || ai.url;
+
+export function studioBanner({ version, url, library, ai = null, multiuser = false, usersDir = "", pid = process.pid, isLibrary = true }) {
+  const iaLine = !ai || !(ai.url || ai.adaptador)
+    ? "  IA: não configurada. No Studio, clique em IA desligada (ou Configurar IA na biblioteca) e informe provedor e chave."
+    : `  IA: ${providerName(ai)} · texto ${ai.textModel}${ai.source === "variável" ? " (pelas variáveis SAGADECK_LLM_*)" : ""}`;
+  return [
+    `✓ SagaDeck Studio ${version} pronto. Abra no navegador: ${url}${isLibrary ? "  (biblioteca)" : ""}`,
+    multiuser ? `  multiusuário: bibliotecas em ${usersDir}` : `  biblioteca: ${library}`,
+    iaLine,
+    `  processo ${pid}`,
+  ];
+}