sapiens-mcp 1.78.1 → 1.79.0

package/README.md

@@ -2,6 +2,11 @@
 
 ![Helen Ailith numa mesa escura, antebracos vestidos por um exoesqueleto de luz verde, movendo placas de luz com as maos abertas](https://sapiensinteticos.b-cdn.net/borderlessprotocol/2026/07/1785430717302_e8p3i4.webp)
 
+<p align="center">
+  <a href="https://sapiensinteticos.b-cdn.net/videos/films/abre-alas/sapiens-mcp-intro-pt-3e96346c.mp4"><img src="https://sapiensinteticos.b-cdn.net/videos/films/abre-alas/sapiens-mcp-intro-pt-497bacfa.jpg" width="720" alt="O sapiens-mcp em 15 segundos: você fala, sua IA executa"></a><br>
+  <a href="https://sapiensinteticos.b-cdn.net/videos/films/abre-alas/sapiens-mcp-intro-pt-3e96346c.mp4"><b>Assiste em 15 segundos, com som</b></a> · <a href="https://sapiensinteticos.b-cdn.net/videos/films/abre-alas/sapiens-mcp-intro-9x16-pt-b5b02542.mp4">corte vertical</a> · <a href="https://sapiensinteticos.b-cdn.net/videos/films/abre-alas/sapiens-mcp-intro-en-e17d0673.mp4">in English</a>
+</p>
+
 Servidor MCP pra operar o [Sapiens Sintéticos](https://sapiensinteticos.com) direto do Claude Code, **na sua própria conta**. Você pede no Claude ("gera uma imagem disso", "escreve um artigo sobre aquilo") e ele faz, gastando as **suas Sinapses**, salvando no **seu perfil**.
 
 ## Pré-requisito
@@ -42,6 +47,29 @@ O token vale 90 dias e renova sozinha a cada uso; fica salvo em `~/.sapiens-mcp/
 
 O Claude avisa o custo antes de gastar, e geração que falha é estornada. Publicar no blog editorial, Coluna Sapiens e o pipeline são exclusivos do dono da plataforma.
 
+## Gerar com a sua chave (0 Sinapse)
+
+Tem crédito na fal ou na Kie? Ponha a chave no `env` do servidor, no config do seu cliente, e a `sapiens_pontes` gera no provedor com ela e traz a peça pro seu acervo. Você paga o preço do provedor; a casa cobra zero em cima.
+
+```json
+{
+  "mcpServers": {
+    "sapiens": {
+      "command": "npx",
+      "args": ["-y", "sapiens-mcp"],
+      "env": {
+        "FAL_KEY": "cole-aqui-a-chave-da-fal",
+        "KIE_API_KEY": "cole-aqui-a-chave-da-kie"
+      }
+    }
+  }
+}
+```
+
+No Claude Code: `claude mcp add sapiens --env FAL_KEY=sua-chave -- npx -y sapiens-mcp`. Depois é só pedir: "gera um retrato da Vera na fal com a minha chave".
+
+A chave fica na sua máquina e sai dela só pro provedor: não vai em argumento, não volta em resultado, não passa pelo servidor do Sapiens. Por isso a `sapiens_pontes` existe só aqui, no servidor instalado; o conector remoto (claude.ai, ChatGPT) não recebe chave. Os jobs ficam em `~/.sapiens-mcp/pontes-jobs.json`, e o mesmo pedido repetido em 30 minutos devolve o job que já existe em vez de cobrar de novo.
+
 ## Troubleshooting
 
 - **"sessionToken expirado" / "Conta Sapiens não conectada".** A chave venceu (90 dias sem uso) ou nunca foi salva. Abra [sapiensinteticos.com/conectar-claude](https://www.sapiensinteticos.com/conectar-claude) logado, gere um código novo e rode `sapiens_meta action=login code=XXXX-XXXX`.
@@ -51,7 +79,7 @@ O Claude avisa o custo antes de gastar, e geração que falha é estornada. Publ
 
 ## Privacidade
 
-O servidor só conversa com o backend público do Sapiens (Convex). Sua identidade vem sempre do token de login, nunca de parâmetros soltos. Cada conta só mexe no que é dela.
+O servidor conversa com o backend público do Sapiens (Convex) e, só quando você gera com a sua chave, com o provedor dela (fal ou Kie), direto da sua máquina. Sua identidade vem sempre do token de login, nunca de parâmetros soltos. Cada conta só mexe no que é dela.
 
 ## Sobre o Sapiens Sintéticos
 

package/dist/pisoDeIdade.js

@@ -0,0 +1,145 @@
+/**
+ * PISO DE IDADE da casa, na porta local das Pontes (sapiens_pontes).
+ *
+ * CÓPIA dos padrões de apps/sapiens/convex/shared/characterSoulGuard.ts. O MCP
+ * é pacote separado e não importa o app, então os padrões moram duplicados; a
+ * paridade é travada por apps/sapiens/convex/shared/pisoDeIdade.parity.test.ts,
+ * que quebra se um lado mudar sem o outro. Mexeu num, mexa no outro.
+ *
+ * Por que existe aqui: na porta local, quem chama o motor é o código da casa,
+ * inclusive em peso aberto sem freio (fal). O prompt passa por esta peneira
+ * ANTES de sair da máquina, com a mesma régua da alma do personagem: 18 é o
+ * piso, e a palavra que o gerador lê como criança não sai daqui.
+ *
+ * Módulo PURO: sem import, sem rede, sem disco.
+ */
+// Abaixo de 18 em número (1 a 17) e por extenso (pt-BR, pt-PT e inglês).
+// Zero e "um/uma" ficam fora: "tem um ano de casa" é do projeto, não de gente.
+const PT_MINOR_WORDS = "dois|duas|tr[êe]s|quatro|cinco|seis|sete|oito|nove|" +
+    "dez|onze|doze|treze|catorze|quatorze|quinze|dezesseis|dezasseis|dezessete|dezassete";
+const EN_MINOR_WORDS = "one|two|three|four|five|six|seven|eight|nine|" +
+    "ten|eleven|twelve|thirteen|fourteen|fifteen|sixteen|seventeen";
+const NUM_MINOR_CORE = `(?:1[0-7]|[1-9]|${PT_MINOR_WORDS}|${EN_MINOR_WORDS})`;
+// Sempre entre \b: "25 anos" não casa "5 anos", "18" não casa "1".
+const NUM_MINOR = `\\b${NUM_MINOR_CORE}\\b`;
+// Substantivo que, ligado a "de N anos", fala de uma PESSOA (o que torna o
+// "de" inequívoco). Sem ele, "de 15 anos" também casa "há mais de 15 anos".
+const PT_PERSON = "menin[oa]s?|garot[oa]s?|jovem|jovens|mo[çc][ao]s?|rapaz(?:es)?|mulher(?:es)?|homens?|" +
+    "estudantes?|alun[oa]s?|filh[oa]s?|irm[ãa]o?s?|irm[ãa]s?|prim[oa]s?|sobrinh[oa]s?|" +
+    "namorad[oa]s?|noiv[oa]s?|person(?:agem|agens)|ele|ela";
+// Sujeito que torna "is N" idade de alguém: pronome, substantivo de pessoa ou
+// nome próprio (palavra capitalizada). "the list is 12 items" não tem sujeito
+// de gente, então passa.
+const EN_PERSON = "she|he|who|girl|boy|woman|man|kid|character|daughter|son|sister|brother|" +
+    "niece|nephew|cousin|friend|student|[A-ZÀ-Ý][a-zà-ÿ]+";
+// "N anos" depois de vírgula é idade ("Tavi, 17 anos"), salvo quando o resto
+// da frase diz que é intervalo: "voltou, 15 anos depois", "15 anos de estrada".
+const PT_INTERVAL_TAIL = "(?!\\s+(?:de\\s+(?!idade\\b)|depois|antes|atr[áa]s|ap[óo]s|mais\\s+tarde|se\\s+passaram))";
+// Nome próprio antes da vírgula: palavra capitalizada que NÃO é numeral
+// ("Três, quatro, sete palavras" é contagem, não "Nome, N"). A lista é
+// case-sensitive de propósito, é só a inicial maiúscula que interessa.
+const CAPITALIZED_NUMERALS = `${PT_MINOR_WORDS}|${EN_MINOR_WORDS}`
+    .split("|")
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join("|");
+const PT_NAME_BEFORE_COMMA = `\\b(?!(?:${CAPITALIZED_NUMERALS})\\b)[A-ZÀ-Ý][^\\s,;.()]{1,30},\\s*`;
+// O que fecha "Nome, N" como idade: fim de oração, ou vírgula que NÃO abre
+// outro número ("Gamma, 2,1 m" é medida; "Três, quatro, sete" é contagem).
+const PT_BARE_TAIL = `(?![,.]\\d)(?=\\s*(?:[.;!?)\\n]|$|,\\s*(?!\\d|(?:${PT_MINOR_WORDS}|${EN_MINOR_WORDS})\\b)))`;
+// O que vem depois de "is N" pra ser idade: fim de oração ou a própria palavra
+// idade. "is 12 by 14", "was 16 strong", "is 15,000 lines" ficam de fora.
+const EN_AGE_TAIL = "(?!,\\d)(?=\\s*(?:[.,;!?)\\n]|$|years?[- ]old\\b|yo\\b|y\\.o\\.|and\\b|now\\b|today\\b))";
+// Unidade que desfaz "aged/turned N" como idade: "turned 15 years ago",
+// "only 15 minutes", "is 15%".
+const EN_UNIT_TAIL = "(?!\\s*(?:%|:|h\\b|am\\b|pm\\b|st\\b|nd\\b|rd\\b|th\\b|minutes?|mins?|seconds?|hours?|days?|weeks?|months?|km|kg|cm|percent|years?\\s+(?:ago|later|of|in|on|since)))";
+/** Os padrões, idênticos aos do servidor (ver o cabeçalho). */
+export const MINOR_PATTERNS = [
+    // pt-BR: a palavra que o gerador lê como criança.
+    { re: /\bcrian[çc]as?\b/i, label: "criança" },
+    { re: /\badolescentes?\b/i, label: "adolescente" },
+    { re: /\bmenor(?:es)?\s+de\s+idade\b/i, label: "menor de idade" },
+    { re: /\bmenin[oa]s?\b/i, label: "menino/menina" },
+    // pt-BR: idade dita em número, só com o verbo/preposição que a torna idade
+    // de alguém. "há 15 anos" e "faz 15 anos que mora em Lisboa" passam
+    // ("faz" fica fora de propósito: é o "há" falado).
+    {
+        re: new RegExp(
+        // "tem 10 anos de estrada" passa; "tem 16 anos de idade" cai.
+        `\\b(?:tem|tenho|tinha|tinham|t[êe]m|aos|fez|completou|completa|completa[rn])\\s+(?:apenas\\s+|s[óo]\\s+)?${NUM_MINOR}\\s+anos?\\b(?!\\s+de\\s+(?!idade\\b))`, "i"),
+        label: "tem/aos N anos (abaixo de 18)",
+    },
+    {
+        // "ela tem 17." (sem "anos"): só quando a oração acaba no número.
+        // "tem 15 tatuagens" passa.
+        re: new RegExp(`\\b(?:tem|tenho|tinha|tinham|t[êe]m)\\s+(?:apenas\\s+|s[óo]\\s+)?${NUM_MINOR}(?=\\s*(?:[.,;!?)\\n]|$))`, "i"),
+        label: "tem N (abaixo de 18)",
+    },
+    {
+        re: new RegExp(`\\bcom\\s+${NUM_MINOR}\\s+anos?\\b(?!\\s+de\\s+\\w)`, "i"),
+        label: "com N anos (abaixo de 18)",
+    },
+    { re: new RegExp(`${NUM_MINOR}\\s+anos?\\s+de\\s+idade\\b`, "i"), label: "N anos de idade (abaixo de 18)" },
+    {
+        re: new RegExp(`\\b(?:${PT_PERSON})\\s+de\\s+${NUM_MINOR}\\s+anos?\\b`, "i"),
+        label: "pessoa de N anos (abaixo de 18)",
+    },
+    {
+        // O formato canônico da primeira linha: "Você é Tavi, 17 anos". Pede o
+        // nome antes da vírgula: "financiada, dez anos ainda pra pagar" passa.
+        re: new RegExp(`${PT_NAME_BEFORE_COMMA}${NUM_MINOR}\\s+anos?\\b${PT_INTERVAL_TAIL}`),
+        label: "'Nome, N anos' (abaixo de 18)",
+    },
+    {
+        // Nome seguido só do número: "Rin, 17." / "Tavi, 17, estudante".
+        re: new RegExp(`${PT_NAME_BEFORE_COMMA}${NUM_MINOR}${PT_BARE_TAIL}`),
+        label: "'Nome, N' (abaixo de 18)",
+    },
+    {
+        // Nome com a idade entre parênteses: "Rin (16)".
+        re: new RegExp(`\\b[A-ZÀ-Ý][^\\s(]{1,30}\\s*\\(\\s*${NUM_MINOR}\\s*(?:anos?|years?\\s+old|yo)?\\s*\\)`),
+        label: "'Nome (N)' (abaixo de 18)",
+    },
+    {
+        // Rótulo de ficha: "Idade: 17", "Age: 16", "idade = 15".
+        re: new RegExp(`\\b(?:idade|age)\\s*[:=]\\s*(?:apenas\\s+|s[óo]\\s+|only\\s+|just\\s+)?${NUM_MINOR}`, "i"),
+        label: "Idade: N (abaixo de 18)",
+    },
+    // inglês: mesma régua.
+    { re: /\bteen(?:s|age|aged|ager|agers)?\b/i, label: "teen" },
+    { re: /\bpre-?teens?\b/i, label: "preteen" },
+    { re: /\bunderage\b/i, label: "underage" },
+    { re: /\bchild(?:ren)?\b/i, label: "child" },
+    // "minor" fora da acepção musical/adjetiva ("minor key", "minor detail").
+    {
+        re: /\bminors?\b(?!\s+(?:key|chord|scale|detail|details|role|injur\w*|issue|issues|setback|note|notes|tweak|tweaks|fix|fixes|thing|things|point|points|character|characters|deity|deities|arcana|league|leagues|surgery|change|changes|glitch|scratch))/i,
+        label: "minor",
+    },
+    { re: /\b(?:loli|lolita|shota)\b/i, label: "loli/shota" },
+    { re: new RegExp(`${NUM_MINOR}[- ]years?[- ]old\\b`, "i"), label: "N years old (under 18)" },
+    // "17yo" não tem fronteira entre o 7 e o y, então o núcleo entra sem o \b final.
+    { re: new RegExp(`\\b${NUM_MINOR_CORE}\\s*(?:yo\\b|y\\.o\\.?)`, "i"), label: "Nyo (under 18)" },
+    {
+        // "aged 14", "age of 12", "turned 16"; "turned 15 years ago" e
+        // "only 15 minutes" passam pelo lookahead de unidade.
+        re: new RegExp(`\\b(?:aged?|age\\s+of|turned|turning)\\s+(?:only\\s+|just\\s+)?${NUM_MINOR}${EN_UNIT_TAIL}`, "i"),
+        label: "aged/turned N (under 18)",
+    },
+    {
+        // "she is 16", "Tavi was 15.", "he's 14": só com sujeito de gente e
+        // com a oração acabando no número. "the list is 12 items" passa.
+        re: new RegExp(`\\b(?:${EN_PERSON})(?:'s|\\s+is|\\s+was|\\s+turns)\\s+(?:only\\s+|just\\s+)?${NUM_MINOR}${EN_AGE_TAIL}`),
+        label: "she is N (under 18)",
+    },
+];
+/** Devolve todos os trechos que caem na peneira (vazio = passou). */
+export function findMinorMarkers(text) {
+    if (!text)
+        return [];
+    const out = [];
+    for (const { re, label } of MINOR_PATTERNS) {
+        const m = text.match(re);
+        if (m)
+            out.push({ match: m[0], label });
+    }
+    return out;
+}

package/dist/registry.js

@@ -5,6 +5,7 @@ import { image, imageSchema } from "./tools/image.js";
 import { meta, metaSchema } from "./tools/meta.js";
 import { repertorio, repertorioSchema } from "./tools/repertorio.js";
 import { gallery, gallerySchema } from "./tools/gallery.js";
+import { pontes, pontesSchema } from "./tools/pontes.js";
 import { community, communitySchema } from "./tools/community.js";
 import { article, articleSchema } from "./tools/article.js";
 import { quotePop, quotePopSchema } from "./tools/quotePop.js";
@@ -86,6 +87,11 @@ export const TOOLS = {
         schema: gallerySchema,
         handler: gallery,
     },
+    sapiens_pontes: {
+        description: "GERAR COM A CHAVE DA PESSOA (só no MCP instalado): a outra porta ao lado da Sinapse. Chama o provedor com a chave que mora no ambiente DESTA máquina (o env do config do cliente MCP: FAL_KEY, KIE_API_KEY) e traz a peça pro acervo como nativa, custo 0 em Sinapses: a pessoa paga o preço do provedor, sem margem da casa. A chave NUNCA vai em arg, prompt ou chat, nunca volta no resultado e nunca passa pelo Sapiens: a tool lê do ambiente e o pedido sai daqui direto pro provedor. No conector remoto (claude.ai, ChatGPT) esta tool não existe; lá é Sinapse (sapiens_image, sapiens_video) ou o harness da pessoa + sapiens_gallery action=ingest. Sub-actions: 'balcoes' (quais chaves estão configuradas, pelo NOME, e como configurar; grátis, sem rede), 'gerar' (provedor 'fal' ou 'kie' + modelo = o slug NO PROVEDOR, igual à página do modelo (fal: o id do endpoint, ex 'fal-ai/flux/dev'; Kie: o 'model' do Market) + input = o corpo que a doc do provedor descreve pra esse modelo, com o prompt DENTRO. COBRA NA CONTA DA PESSOA no provedor: confirme modelo e custo com ela antes. O job fica gravado nesta máquina ANTES de esperar o render, e o pedido idêntico em 30 minutos devolve o job que já existe em vez de cobrar de novo (forcar=true repete de propósito). Espera até aguardarSegundos (padrão 45) e, pronto, ingere sozinho com characterId, referenceImageIds, prompt verbatim e o custo quando o provedor diz), 'status' (jobId: consulta o provedor e, se terminou, traz pro acervo; é o que se chama depois de um gerar que voltou 'rodando', NUNCA gerar de novo), 'jobs' (os jobs desta máquina, sem rede). A FICHA DO PERSONAGEM entra no input: pegue passportPrompt e mainImageUrl/imageUrls em sapiens_character action=get, ponha o descritor no começo do prompt e as imagens no campo de referência que o modelo aceita (image_url, image_urls, conforme a doc dele); o bloco NEGATIVE do passaporte vai no campo negative_prompt quando o modelo tem um. O prompt passa pelo piso de idade da casa antes de sair (18 é o piso). Peça de fal entra com o carimbo +18 por classe (peso aberto), igual ao ingest manual; Kie entra sem. Passo a passo na skill 'pontes'.",
+        schema: pontesSchema,
+        handler: pontes,
+    },
     sapiens_community: {
         description: "Chat da comunidade Sapiens (assinantes + alumni). Sub-actions: list (últimas N mensagens da sala 'geral' por default), send (Claude posta como intercessor do user; sufixo '· via Claude' é adicionado pelo servidor), react (toggle emoji numa mensagem — allowlist 👍🔥❤️🚀🤯), participants (quem está na sala: username/name/isBot + o `mention` pronto pra usar — use pra saber com quem falar), search_users (acha alguém por parte do nome/@username, autocomplete de menção). MENÇÃO: escreva '@username' no content do send e o servidor NOTIFICA a pessoa citada (sino + Telegram); descubra o username certo via participants/search_users antes. ANEXO do PRÓPRIO acervo no send: mediaAssetKind (track|video|film|comic) + mediaAssetId monta um card da peça (posse conferida no servidor); asTese=true posta a fala como TESE (card de marca, pingável pro Fórum). Voz nas postagens deve seguir o DNA editorial Sapiens (anti-corporate, primeira pessoa, sem em-dash).",
         schema: communitySchema,
@@ -122,7 +128,7 @@ export const TOOLS = {
         handler: persona,
     },
     sapiens_helen: {
-        description: "Helen Voice TTS via ElevenLabs, Google Gemini ou Fish Audio (qualquer logado; cobra Sinapses). Sub-actions: list_presets (catálogo de voiceIds/voiceNames recomendados + stylePreambles), speak (sintetiza, retorna audioBase64+mimeType+sizeBytes). provider=fish é o S2.1 Pro, o mais forte em japonês, mandarim e coreano: fala de personagem e cena de anime pedem ele. `language` escolhe o idioma (auto|pt|en|ja|es|ko|zh|fr|it|de). BYOK suportado via clientApiKey, senão usa env do deploy. Custo: ElevenLabs ~$0.30/500c, Google ~$0.01/500c, Fish grátis via API até 31/08/2026. Max 5000 chars (quebra antes em chunks). text pré-processado pelo caller (sem em-dash, sem markdown).",
+        description: "Helen Voice TTS via ElevenLabs, Google Gemini ou Fish Audio (qualquer logado; cobra Sinapses). Sub-actions: list_presets (catálogo de voiceIds/voiceNames recomendados + stylePreambles), speak (sintetiza, retorna audioBase64+mimeType+sizeBytes). provider=fish é o S2.1 Pro, o mais forte em japonês, mandarim e coreano: fala de personagem e cena de anime pedem ele. `language` escolhe o idioma (auto|pt|en|ja|es|ko|zh|fr|it|de). A fala sai sempre em Sinapses: a casa não recebe chave de provedor, e clientApiKey é recusado sem cobrar. Custo: ElevenLabs ~$0.30/500c, Google ~$0.01/500c, Fish grátis via API até 31/08/2026. Max 5000 chars (quebra antes em chunks). text pré-processado pelo caller (sem em-dash, sem markdown).",
         schema: helenSchema,
         handler: helen,
     },
@@ -256,7 +262,7 @@ REGRA DE OURO:
 - PRIMEIRO CONTATO ou "o que você faz?"/"como começo?"/"o que dá pra fazer?": chame sapiens_meta action=start e MOSTRE o resultado na sua voz. Sem login, ele ensina a conectar; logado, traz saldo + primeiros poderes com exemplos. É a porta de entrada: não despeje a lista inteira de tools, deixe o start guiar.
 - LOGO APÓS UM LOGIN BEM-SUCEDIDO (action=login retornou ok): chame action=start na sequência e mostre a porta de entrada. O recém-chegado não sabe o que pedir; não o deixe na tela em branco, guie a primeira jogada sem ele precisar perguntar.
 - Antes de gerar algo caro (imagem/música/vídeo), cheque saldo: sapiens_meta action=credits (ou subscription). Saldo baixo, avise o usuário antes. Vídeo é o mais caro da casa: confirme com ele antes de disparar.
-- SEM SALDO, ou motor que a casa não tem: a casa é ponte, não muro. Se a pessoa tem crédito na Kie, na fal, na Magnific, na Sogni ou na própria placa, ela gera LÁ com a ficha do personagem daqui (sapiens_character action=get) e a peça volta pro acervo por sapiens_gallery action=ingest. A chave dela NUNCA passa pelo Sapiens (nem em arg, nem no chat). sapiens_meta action=pontes diz o que ela já tem configurado; skill 'pontes' tem o passo a passo.
+- DUAS PORTAS, lado a lado: Sinapse (sapiens_image, sapiens_video: nada pra configurar) ou a CHAVE DA PESSOA num provedor (fal, Kie, Sogni, a própria placa), que custa zero aqui. No MCP instalado, sapiens_pontes gera com a chave que mora no config dela e traz a peça pro acervo; no remoto, ela gera no harness dela e traz por sapiens_gallery action=ingest. sapiens_meta action=pontes diz o que ela já tem configurado: se tiver chave, ofereça as duas portas antes de gastar Sinapse. A chave NUNCA passa pelo Sapiens (nem em arg, nem no chat). Skill 'pontes'.
 - REGRA DO TIMEOUT: geração SÍNCRONA pode estourar o teto de ~120s do cliente e voltar 'Timeout' MESMO tendo gerado e COBRADO. Nunca repita às cegas: confira antes onde o resultado cairia (a tabela de onde conferir está na skill 'primeiros-passos').
 - "sessionToken expirado" = refaça login: sapiens_meta action=login com o código de sapiensinteticos.com/conectar-claude.
 - sapiens_meta action=formats devolve os schemas por formato; action=whoami diz tier (user/admin) + saldo. sapiens_image e sapiens_video action=models trazem o catálogo com o preço ATUAL: consulte em vez de chutar custo.
@@ -292,6 +298,7 @@ const TOOL_TITLES = {
     sapiens_skill: "Skills da Casa",
     sapiens_repertorio: "Repertório",
     sapiens_gallery: "Galeria de Imagens",
+    sapiens_pontes: "Pontes: gerar com a sua chave",
     sapiens_community: "Chat da Comunidade",
     sapiens_article: "Blog Editorial",
     sapiens_write: "Artigos do Perfil",
@@ -343,14 +350,22 @@ const ADMIN_ONLY_TOOLS = new Set([
     // (requireAdmin em convex/voiceJp.ts): sai daqui e do gate de la juntos.
     "sapiens_voice_jp",
 ]);
+// Tools que só existem no processo LOCAL (stdio), na máquina da pessoa: somem
+// do tools/list do remoto. sapiens_pontes lê a chave de provedor do ambiente da
+// máquina; no remoto o processo é o servidor do site, e chave de membro não
+// sobe (docs/infra/pontes-traga-seu-motor.md). O handler também recusa no
+// remoto, pra chamada de cliente com a lista velha em cache.
+const LOCAL_ONLY_TOOLS = new Set(["sapiens_pontes"]);
 /**
  * Monta o payload do tools/list pro tier dado. Tier "user" esconde as
  * admin-only; desconhecido (null) = lista cheia (fail-open, retrocompat).
+ * `transport` "remote" esconde as que só rodam na máquina da pessoa.
  */
-export function buildToolList(tier) {
+export function buildToolList(tier, transport = "stdio") {
     const filtered = tier === "user";
     return Object.entries(TOOLS)
         .filter(([name]) => !filtered || !ADMIN_ONLY_TOOLS.has(name))
+        .filter(([name]) => transport === "stdio" || !LOCAL_ONLY_TOOLS.has(name))
         .map(([name, t]) => ({
         name,
         description: t.description,

package/dist/remote.js

@@ -170,7 +170,7 @@ function initServer(mcp) {
         }
         // Transiente: serve o catálogo cheio (o gate de verdade é no tools/call).
         const tier = session.status === "valid" ? session.tier : null;
-        return { tools: buildToolList(tier) };
+        return { tools: buildToolList(tier, "remote") };
     });
     s.setRequestHandler(ListPromptsRequestSchema, async () => ({
         prompts: listPrompts(),

package/dist/skills.js

@@ -734,13 +734,15 @@ A foto NUNCA vai pra banco nenhum, nem da casa nem de terceiro:
     },
     {
         name: "pontes",
-        title: "Pontes: gerar fora com crédito próprio e trazer pro acervo",
-        description: "A pessoa tem crédito na Kie, na fal, na Magnific, na Sogni ou na própria placa e quer usar o personagem dela lá, ou está sem Sinapse pra vídeo. Como levar a ficha, gerar no balcão dela (a chave nunca passa pelo Sapiens) e trazer a peça de volta por sapiens_gallery action=ingest, com a ficha inteira. Puxe quando ouvir 'tem Kie aí?', 'uso a fal', 'gastei minhas Sinapses', 'gero na Magnific', 'tenho ComfyUI'.",
+        title: "Pontes: gerar com a sua chave e trazer pro acervo",
+        description: "A pessoa tem crédito na Kie, na fal, na Magnific, na Sogni ou na própria placa e quer usar o personagem dela lá, quer gerar com a chave dela em vez de Sinapse, ou está sem Sinapse pra vídeo. Como levar a ficha, gerar no balcão dela (no MCP instalado, fal e Kie saem pela sapiens_pontes; a chave nunca passa pelo Sapiens) e a peça voltar pro acervo com a ficha inteira. Puxe quando ouvir 'gera com a minha chave', 'tenho FAL_KEY', 'tem Kie aí?', 'uso a fal', 'gastei minhas Sinapses', 'gero na Magnific', 'tenho ComfyUI'.",
         body: `## O que é uma ponte
 
 O Sapiens é uma das pontes, não um muro. A pessoa monta o personagem aqui (ficha, passaporte, referências) e gera a peça ONDE TEM CRÉDITO: Kie, fal, Magnific, Sogni, Krea, Replicate, a própria placa. A peça volta pro acervo dela como NATIVA, com motor, prompt, custo real e personagem na ficha, custo 0 em Sinapses. O portfólio dela cresce aqui; o dinheiro dela sai de onde ela já pôs.
 
-**A regra da chave, sem exceção:** a chave do provedor NUNCA passa pelo Sapiens. Não vai em arg de tool, não vai em prompt, não vai colada no chat. Ela mora no ambiente da pessoa (variável \`FAL_KEY\`, \`KIE_API_KEY\`, um conector MCP do provedor ligado na conversa, o SDK dela) e quem chama o motor é o harness dela, na máquina dela. O Sapiens entra ANTES (a ficha) e DEPOIS (o ingest). Se a pessoa colar a chave no chat por engano, diga pra ela rotacionar a chave no provedor, e siga sem usar o valor.
+São duas portas lado a lado, e nenhuma é a reserva da outra: Sinapse (sapiens_image, sapiens_video) é pra quem não quer configurar nada; a chave própria é pra quem já tem crédito num provedor, e aí a casa não cobra nada em cima: ela paga o preço do provedor, sem margem nossa. Quando a pessoa tem chave configurada, ofereça as duas.
+
+**A regra da chave, sem exceção:** a chave do provedor NUNCA passa pelo Sapiens. Não vai em arg de tool, não vai em prompt, não vai colada no chat. Ela mora no ambiente da máquina da pessoa (o env do config do cliente MCP com \`FAL_KEY\`, \`KIE_API_KEY\`; um conector MCP do provedor ligado na conversa; o SDK dela) e quem chama o motor é um processo DA MÁQUINA DELA: o \`sapiens-mcp\` instalado (sapiens_pontes) ou o harness dela. O Sapiens entra ANTES (a ficha) e DEPOIS (o ingest). Se a pessoa colar a chave no chat por engano, diga pra ela gerar uma chave nova no provedor e pôr a nova no config, e siga sem usar o valor.
 
 ## Passo 1: descobrir onde a pessoa tem crédito
 
@@ -764,7 +766,19 @@ Confirme com ela ANTES de disparar em qualquer balcão pago. Geração de fora t
 
 Regras que valem fora igual dentro: prompt SEM idade em número; personagem nunca menor (a casa trabalha com 23+ no foco e 18 é piso absoluto); motor citado pelo nome que ele tem no provedor. Prompt novo que funcionar lá fora: grave de volta com \`sapiens_character action=set_passport\` (campo \`recipes\`, prompt verbatim + note com o que provou). É isso que faz a próxima rodada não redescobrir.
 
-## Passo 3: gerar lá fora
+## Passo 3a: gerar pela porta local (fal e Kie, MCP instalado)
+
+Com o \`sapiens-mcp\` instalado e a chave no env do config, é a porta mais curta, e funciona até no Claude Desktop, que não tem terminal:
+
+1. \`sapiens_pontes action=balcoes\` diz quais chaves estão configuradas (pelo nome, sem ler o valor). Faltando, mande a pessoa pôr a chave no config: sapiensinteticos.com/conectar-claude#suas-chaves.
+2. Confirme com ela o modelo e o custo no provedor. É dinheiro dela.
+3. \`sapiens_pontes action=gerar\` com \`provedor\` ('fal' ou 'kie'), \`modelo\` (o slug como está na página do modelo no provedor) e \`input\` (o corpo que a doc do modelo descreve, com o prompt DENTRO), mais \`characterId\` e \`referenceImageIds\` pra ficha. O descritor do passaporte vai no começo do prompt; o bloco NEGATIVE vai no campo \`negative_prompt\` quando o modelo tem um (no corpo do prompt, negação acende o que proíbe, e o piso de idade da casa recusa palavra de menor ali). As imagens da ficha vão no campo de referência do modelo (\`image_url\`, \`image_urls\`).
+4. Voltou \`rodando\`? Chame \`sapiens_pontes action=status jobId=...\`, nunca \`gerar\` de novo: o job está gravado na máquina dela, e o pedido idêntico em 30 minutos devolve o job que existe em vez de cobrar outra vez.
+5. Terminado, a peça entra sozinha no acervo, privada, custo 0 em Sinapses, com motor, prompt verbatim e custo na ficha. Mostre com \`sapiens_gallery action=list\`.
+
+No remoto (claude.ai, ChatGPT) a porta local não existe, porque a chave não sobe: ali é o Passo 3b.
+
+## Passo 3b: gerar pelo harness (os outros balcões, ou no remoto)
 
 O que a casa MEDIU em cada balcão (o resto está na doc do provedor; não invente parâmetro):
 
@@ -782,7 +796,7 @@ Não repita geração paga às cegas: se a chamada deu timeout, consulte o job n
 
 ## Passo 4: trazer pra casa
 
-\`sapiens_gallery action=ingest\`, no MESMO turno do render (URL de render expira):
+Pela porta local (3a) isto já aconteceu sozinho. Pelo harness (3b), \`sapiens_gallery action=ingest\`, no MESMO turno do render (URL de render expira):
 
 - A peça: \`filePath\` (arquivo local; só no MCP instalado, é a porta de quem gerou na máquina ou baixou antes), ou \`sourceUrl\` (o link do render; quem baixa é o MCP na máquina da pessoa, não o servidor), ou \`base64\` (imagem).
 - \`externalEngine\`: \`provedor-motor\`, sempre. \`kie-kling-3.0\`, \`fal-krea-2\`, \`sogni-minimax-h3\`, \`magnific-seedance-2.5\`, \`bancada-ltx-2.5\`. Marca sozinha é recusada: é este campo que a ficha mostra em "Motor".

package/dist/tools/distribution.js

@@ -193,7 +193,7 @@ export const distributionSchema = z.object({
     lang: z
         .enum(["pt", "en"])
         .optional()
-        .describe("lineage-new/lineage-save: a língua em que a linhagem fala. queue: em que LÍNGUA a copy JÁ ESTÁ. Declare sempre que escrever a copy você mesmo. Sem este campo, canal de rede internacional (bluesky, x, linkedin, farcaster, civitai, pinterest, reddit, medium, tumblr, deviantart) presume que a copy chegou em português e agenda uma vertida automática que SOBRESCREVE o que você mandou, dois segundos depois de enfileirar. Copy que já estava em inglês volta reescrita, e na voz da CASA em vez da voz de quem assina a peça, o que estraga copy de personagem. Declarar o idioma desliga a vertida e o texto fica exatamente como você mandou."),
+        .describe("lineage-new/lineage-save: a língua em que a linhagem fala. queue: em que LÍNGUA a copy JÁ ESTÁ. Declare sempre que escrever a copy você mesmo. Sem este campo, canal de rede internacional (bluesky, linkedin, youtube, tiktok, threads, farcaster, civitai, pinterest, reddit, medium, tumblr, deviantart, e os X que não são o x e o x-buffer do dono) presume que a copy chegou em português e agenda uma vertida automática que SOBRESCREVE o que você mandou, dois segundos depois de enfileirar. Copy que já estava em inglês volta reescrita, e na voz da CASA em vez da voz de quem assina a peça, o que estraga copy de personagem. Declarar o idioma desliga a vertida e o texto fica exatamente como você mandou."),
     voice: z
         .string()
         .optional()

package/dist/tools/helen.js

@@ -63,10 +63,14 @@ export const helenSchema = z.object({
         .string()
         .optional()
         .describe("ElevenLabs ex 'mp3_44100_128'. Default da provider."),
+    // Fica no schema de propósito, pra RECUSAR: sem o campo, o Zod descartaria a
+    // chave calado e a fala sairia cobrando Sinapses de quem achou que pagava com
+    // a própria chave. Desde 27/09/2026 a casa não recebe chave de provedor por
+    // caminho nenhum (docs/infra/pontes-traga-seu-motor.md).
     clientApiKey: z
         .string()
         .optional()
-        .describe("BYOK: chave do user. Se vazia, usa env default do deploy (ELEVENLABS_API_KEY ou GEMINI_API_KEY)."),
+        .describe("DESLIGADO desde 27/09/2026: a casa não recebe chave de provedor. Não mande: a chamada é recusada sem cobrar. A fala sai sempre em Sinapses."),
 });
 const PRESETS = {
     elevenlabs: {
@@ -112,6 +116,9 @@ export async function helen(args) {
         if (!args.text || !args.text.trim()) {
             throw new Error("action=speak exige text (não vazio).");
         }
+        if (args.clientApiKey?.trim()) {
+            throw new Error("A voz com a sua chave saiu: a casa não recebe chave de provedor por caminho nenhum, ela fica na sua máquina. Esta fala não foi feita e nada foi cobrado. Mande de novo sem clientApiKey e ela sai em Sinapses. Se a chave foi colada no chat, gere uma nova no provedor.");
+        }
         const provider = args.provider ?? "elevenlabs";
         const modelId = args.modelId ??
             (provider === "elevenlabs"
@@ -140,7 +147,6 @@ export async function helen(args) {
             stylePreamble: args.stylePreamble,
             voiceSettings: args.voiceSettings,
             outputFormat: args.outputFormat,
-            clientApiKey: args.clientApiKey,
         });
     }
 }

package/dist/tools/meta.js

@@ -207,6 +207,8 @@ const PONTES = [
         nota: "Custo zero em dinheiro, pago em tempo. Entra por filePath, slug 'bancada-<motor>'.",
     },
 ];
+/** Os balcões que a sapiens_pontes dirige daqui (os outros vão pelo harness + ingest). */
+const PORTA_LOCAL = ["fal", "kie"];
 const FIRST_POWERS = [
     {
         icon: "📚",
@@ -391,7 +393,7 @@ export async function meta(args) {
             balance,
             ...(lowBalance
                 ? {
-                    balanceWarning: "Saldo abaixo de 500 Sinapses: o que é grátis roda tranquilo, mas pra imagem/música/vídeo talvez precise recarregar. Outra saída é a ponte: se a pessoa tem crédito na Kie, na fal, na Magnific ou na Sogni, gera lá com a ficha do personagem daqui e traz a peça pro acervo por sapiens_gallery action=ingest (skill 'pontes'; sapiens_meta action=pontes diz o que ela já tem configurado).",
+                    balanceWarning: "Saldo abaixo de 500 Sinapses: o que é grátis roda tranquilo, mas pra imagem/música/vídeo talvez precise recarregar. Outra saída é a outra porta: com a chave dela num provedor (Kie, fal, Magnific, Sogni), gera lá com a ficha do personagem daqui e a peça volta pro acervo, custo zero em Sinapses. No MCP instalado, fal e Kie saem daqui mesmo por sapiens_pontes action=gerar; o resto volta por sapiens_gallery action=ingest (skill 'pontes'; sapiens_meta action=pontes diz o que ela já tem configurado).",
                 }
                 : {}),
             firstPowers: FIRST_POWERS,
@@ -556,14 +558,23 @@ export async function meta(args) {
                 const valor = process.env[nome];
                 return typeof valor === "string" && valor.trim().length >= 8;
             })).map((p) => p.key);
+        const naPortaLocal = detectadas.filter((k) => PORTA_LOCAL.includes(k));
         return {
-            regra: "A chave de provedor NUNCA passa pelo Sapiens: quem chama o motor é o seu harness, na sua máquina, com o seu crédito. A casa entra com a ficha do personagem (sapiens_character action=get: passportPrompt + imageUrls) e recebe a peça de volta por sapiens_gallery action=ingest, que grava motor, prompt verbatim, custo real e personagem. Passo a passo: sapiens_skill action=get name=pontes.",
+            regra: "A chave de provedor NUNCA passa pelo Sapiens: ela mora no ambiente da máquina da pessoa e quem chama o motor é um processo de lá (o harness dela, ou o sapiens-mcp instalado pela sapiens_pontes). A casa entra com a ficha do personagem (sapiens_character action=get: passportPrompt + imageUrls) e recebe a peça de volta pelo ingest, que grava motor, prompt verbatim, custo real e personagem. Com a chave dela, gerar custa zero em Sinapses: ela paga o preço do provedor, sem margem da casa. Passo a passo: sapiens_skill action=get name=pontes.",
             detectadas,
             detectadasNota: remoto
-                ? "No MCP remoto não dá pra olhar o ambiente da pessoa: pergunte a ela onde tem crédito (Kie, fal, Magnific, Sogni, Krea...) ou olhe os conectores que já estão nesta conversa."
+                ? "No MCP remoto não dá pra olhar o ambiente da pessoa, e gerar com a chave dela pede o MCP instalado (a chave não sobe pro conector remoto). Pergunte onde ela tem crédito (Kie, fal, Magnific, Sogni, Krea...) ou olhe os conectores que já estão nesta conversa."
                 : detectadas.length
-                    ? `Achei chave configurada (pelo NOME da variável, sem ler o valor) pra: ${detectadas.join(", ")}. Proponha gerar por aí antes de gastar Sinapse.`
-                    : "Nenhuma variável de provedor no ambiente deste MCP. Pergunte onde a pessoa tem crédito, ou olhe os conectores já ligados nesta conversa (Magnific, Krea, Sogni).",
+                    ? `Achei chave configurada (pelo NOME da variável, sem ler o valor) pra: ${detectadas.join(", ")}. Ofereça as duas portas antes de gastar Sinapse.${naPortaLocal.length ? ` ${naPortaLocal.join(" e ")} a casa gera daqui mesmo: sapiens_pontes action=gerar.` : ""}`
+                    : "Nenhuma variável de provedor no ambiente deste MCP. Pergunte onde a pessoa tem crédito, ou olhe os conectores já ligados nesta conversa (Magnific, Krea, Sogni). Pra fal e Kie, a chave vai no env do config do cliente MCP: sapiensinteticos.com/conectar-claude#suas-chaves.",
+            portaLocal: {
+                tool: "sapiens_pontes",
+                balcoes: PORTA_LOCAL,
+                disponivel: !remoto,
+                nota: remoto
+                    ? "Só no MCP instalado: no remoto a tool não existe."
+                    : "Gera no provedor com a chave desta máquina e traz a peça pro acervo sozinha. Os outros balcões seguem pelo harness + ingest.",
+            },
             pontes: PONTES.map((p) => ({
                 key: p.key,
                 nome: p.nome,

package/dist/tools/pontes.js

@@ -0,0 +1,783 @@
+import { z } from "zod";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { describeConvexError, getSessionToken, isRemoteContext, } from "../convexClient.js";
+import { findMinorMarkers } from "../pisoDeIdade.js";
+import { gallery } from "./gallery.js";
+/**
+ * A PORTA LOCAL DAS PONTES (27/09/2026): gerar no provedor com a chave da
+ * PESSOA e trazer a peça pro acervo como nativa, custo 0 em Sinapses.
+ *
+ * Existe porque Sinapse e chave própria andam lado a lado (decisão do dono):
+ * Sinapse é pra quem não quer configurar nada; a chave própria é pra quem já tem
+ * crédito num provedor, e aí a casa não cobra nada em cima. Até esta tool, quem
+ * chamava o provedor era o harness da pessoa, então chave própria era coisa de
+ * quem tem terminal. O Claude Desktop não tem.
+ *
+ * A regra da chave (doc docs/infra/pontes-traga-seu-motor.md): ela mora no
+ * ambiente DESTA máquina (o "env" do config do cliente MCP) e sai daqui só pro
+ * provedor. Não entra em arg, não volta em resultado, não vai pro Convex, não
+ * fica no arquivo de jobs. No transporte remoto a tool nem aparece no
+ * tools/list, e a chamada é recusada antes de ler qualquer coisa: lá o processo
+ * é o servidor do site, e chave de membro não sobe.
+ *
+ * As quatro travas, uma por risco:
+ *   1. Bug nosso gastar o dinheiro dela: o job é gravado em disco ANTES de
+ *      esperar o render, e o pedido idêntico em 30 min devolve o job que existe.
+ *   2. A chave vazar num erro: toda saída passa pelo `semChave`.
+ *   3. Provedor mudar a API: porta genérica, o `input` é o corpo da doc dele.
+ *   4. A casa passar a ser quem gera: o prompt passa pelo piso de idade antes
+ *      de sair, e a peça entra pelo ingest com o carimbo da classe do provedor.
+ */
+const BALCOES = {
+    fal: { nome: "fal.ai", envVar: "FAL_KEY" },
+    kie: { nome: "Kie", envVar: "KIE_API_KEY" },
+};
+/**
+ * Toda variável de chave de provedor que a casa conhece, dirigida por esta tool
+ * ou não: é a lista que o `semChave` limpa. Chave de balcão que a tool não usa
+ * também não pode vazar num erro que ecoe o ambiente.
+ */
+const NOMES_DE_CHAVE = [
+    "FAL_KEY",
+    "KIE_API_KEY",
+    "WAVESPEED_API_KEY",
+    "SOGNI_API_KEY",
+    "KREA_API_KEY",
+    "REPLICATE_API_TOKEN",
+];
+const JANELA_REPETIDO_MS = 30 * 60 * 1000;
+const MAX_JOBS_GUARDADOS = 200;
+const MAX_PECAS_POR_JOB = 4;
+const ESPERA_PADRAO_GERAR_S = 45;
+const ESPERA_PADRAO_STATUS_S = 20;
+const ESPERA_MAX_S = 75;
+// O cliente MCP desiste em ~120s. Trazer um vídeo pro acervo (baixar + subir)
+// leva segundos a dezenas de segundos, então o ingest só começa na mesma
+// chamada se ainda sobra folga; senão o job volta "pronto" e o status traz.
+const INGEST_SO_ATE_MS = 60_000;
+const ENDERECO_SUAS_CHAVES = "https://www.sapiensinteticos.com/conectar-claude#suas-chaves";
+export const pontesSchema = z.object({
+    action: z.enum(["balcoes", "gerar", "status", "jobs"]),
+    provedor: z
+        .enum(["fal", "kie"])
+        .optional()
+        .describe("action=gerar: o balcão. 'fal' lê FAL_KEY; 'kie' lê KIE_API_KEY. As duas moram no env do config do cliente MCP, nesta máquina."),
+    modelo: z
+        .string()
+        .max(200)
+        .optional()
+        .describe("action=gerar: o slug do modelo NO PROVEDOR, igual à página dele. fal: o id do endpoint (ex: 'fal-ai/flux/dev'), que vai no caminho de queue.fal.run. Kie: o campo 'model' do Market (ex: 'kling/v2-1-standard'), que vai no corpo do createTask. Não invente: confira na página do modelo."),
+    input: z
+        .union([z.record(z.any()), z.string()])
+        .optional()
+        .describe("action=gerar: o corpo que a doc do provedor descreve pra esse modelo, com o prompt DENTRO (ex: {\"prompt\": \"...\", \"image_urls\": [\"...\"]}). A ficha do personagem entra aqui: passportPrompt no começo do prompt e mainImageUrl/imageUrls no campo de referência que o modelo aceita. A chave NUNCA vai aqui."),
+    prompt: z
+        .string()
+        .max(20000)
+        .optional()
+        .describe("action=gerar: o prompt verbatim pra ficha da peça, quando ele não mora em input.prompt. Omitido, a ficha usa input.prompt."),
+    jobId: z
+        .string()
+        .optional()
+        .describe("action=status: o id do job local (pj_...), devolvido pelo gerar e listado em action=jobs."),
+    ingerir: z
+        .boolean()
+        .optional()
+        .describe("action=gerar/status: true (padrão) traz a peça pro acervo quando o render termina. false só gera e devolve as URLs do provedor (que expiram)."),
+    aguardarSegundos: z
+        .number()
+        .int()
+        .min(0)
+        .max(ESPERA_MAX_S)
+        .optional()
+        .describe(`action=gerar/status: quanto esperar pelo render nesta chamada (padrão ${ESPERA_PADRAO_GERAR_S} no gerar, ${ESPERA_PADRAO_STATUS_S} no status, teto ${ESPERA_MAX_S}). Imagem costuma sair dentro; vídeo quase nunca: volta 'rodando' e o status termina.`),
+    forcar: z
+        .boolean()
+        .optional()
+        .describe("action=gerar: true gera de novo MESMO com um pedido idêntico nos últimos 30 minutos. Sem isto, o pedido repetido devolve o job que já existe, pra não cobrar duas vezes."),
+    externalEngine: z
+        .string()
+        .max(100)
+        .optional()
+        .describe("action=gerar: o nome do motor na ficha, formato provedor-motor ('fal-krea-2'). Omitido, sai do slug do modelo. O prefixo do provedor é sempre o de verdade: é ele que decide o carimbo +18 da classe."),
+    externalCost: z
+        .string()
+        .max(200)
+        .optional()
+        .describe("action=gerar: o custo pra ficha, quando você sabe ('US$ 0,35 na fal'). Omitido, a Kie informa os créditos consumidos e a fal fica como 'pago na fal com a sua chave'."),
+    characterId: z
+        .string()
+        .optional()
+        .describe("action=gerar: o personagem de quem é a peça (influencers:_id). A peça nasce ligada à ficha dele."),
+    characterIds: z
+        .union([z.array(z.string()), z.string()])
+        .optional()
+        .describe("action=gerar: quem está em cena, em ordem (o protagonista primeiro), quando é mais de uma criatura."),
+    referenceImageIds: z
+        .union([z.array(z.string()), z.string()])
+        .optional()
+        .describe("action=gerar: generatedImages:_id das peças da casa que serviram de referência."),
+    aspectRatio: z.string().max(20).optional().describe("action=gerar: proporção pra ficha ('9:16'). Omitido, lê input.aspect_ratio."),
+    size: z.string().max(20).optional().describe("action=gerar: resolução pra ficha ('720p'). Omitido, lê input.resolution."),
+    unfiltered: z
+        .boolean()
+        .optional()
+        .describe("action=gerar: true quando o modelo rodou sem filtro num balcão que modera (Kie): a peça nasce com o carimbo +18 declarado."),
+    skills: z
+        .union([z.array(z.string()), z.string()])
+        .optional()
+        .describe("action=gerar: os slugs das skills da casa que dirigiram a peça."),
+    limit: z.number().int().positive().max(50).optional().describe("action=jobs: quantos (padrão 10)."),
+});
+// ---------------------------------------------------------------------------
+// A chave: lida do ambiente, nunca devolvida.
+// ---------------------------------------------------------------------------
+function segredosConfigurados() {
+    const out = new Set();
+    for (const nome of NOMES_DE_CHAVE) {
+        const valor = process.env[nome]?.trim();
+        if (!valor || valor.length < 8)
+            continue;
+        out.add(valor);
+        // A chave da fal é "id:segredo": um erro que ecoa só o id ainda identifica
+        // a conta dela, então cada metade também sai.
+        for (const parte of valor.split(":"))
+            if (parte.length >= 8)
+                out.add(parte);
+    }
+    // Maior primeiro: trocar o pedaço antes do inteiro deixaria sobra do inteiro.
+    return [...out].sort((a, b) => b.length - a.length);
+}
+/** Troca qualquer valor de chave configurada por "[chave]". Toda saída passa aqui. */
+export function semChave(texto) {
+    let out = texto;
+    for (const segredo of segredosConfigurados())
+        out = out.split(segredo).join("[chave]");
+    return out;
+}
+function limpo(valor) {
+    return JSON.parse(semChave(JSON.stringify(valor)));
+}
+function chaveDo(provedor) {
+    const { nome, envVar } = BALCOES[provedor];
+    const valor = process.env[envVar]?.trim();
+    if (!valor || valor.length < 8) {
+        throw new Error(`Não achei a ${envVar} nesta máquina. Ponha a chave da ${nome} no "env" do sapiens, no config do seu cliente MCP, e reinicie o cliente: ${ENDERECO_SUAS_CHAVES}. A chave fica no seu computador; nunca mande ela no chat.`);
+    }
+    return valor;
+}
+const CAMPO_DE_CHAVE = /^(api[_-]?key|apikey|x[_-]api[_-]key|secret|client[_-]?secret|access[_-]?token|authorization|fal[_-]?key|kie[_-]?api[_-]?key)$/i;
+function campoDeChave(v, fundo = 0) {
+    if (fundo > 6 || !v || typeof v !== "object")
+        return null;
+    for (const [k, x] of Object.entries(v)) {
+        if (CAMPO_DE_CHAVE.test(k))
+            return k;
+        const achou = campoDeChave(x, fundo + 1);
+        if (achou)
+            return achou;
+    }
+    return null;
+}
+/**
+ * A chave não viaja no pedido. Se ela aparece no input ou no prompt, o pedido
+ * morre aqui, sem sair da máquina, e a mensagem não repete o valor.
+ */
+function confereSemChaveNoPedido(input, prompt) {
+    const corpo = `${JSON.stringify(input)}\n${prompt ?? ""}`;
+    const vazou = segredosConfigurados().some((s) => corpo.includes(s));
+    const campo = campoDeChave(input);
+    if (vazou || campo) {
+        throw new Error(`${campo ? `O input tem um campo de chave ("${campo}")` : "Tem uma chave de API dentro do input ou do prompt"}. A chave não vai no pedido: ela mora no env do config do seu cliente MCP e esta tool lê de lá. Tire do input e, se a chave foi colada no chat, gere uma nova no provedor.`);
+    }
+}
+// ---------------------------------------------------------------------------
+// O pedido: input, prompt, piso de idade, assinatura pro repetido.
+// ---------------------------------------------------------------------------
+function lerInput(raw) {
+    if (raw == null) {
+        throw new Error("action=gerar exige input: o corpo que a doc do provedor descreve pra esse modelo, com o prompt dentro (ex: {\"prompt\": \"...\"}).");
+    }
+    let obj = raw;
+    if (typeof raw === "string") {
+        try {
+            obj = JSON.parse(raw);
+        }
+        catch {
+            throw new Error("input veio como texto e não é JSON válido. Mande o objeto (ex: {\"prompt\": \"...\"}).");
+        }
+    }
+    if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+        throw new Error("input precisa ser um objeto JSON (ex: {\"prompt\": \"...\"}).");
+    }
+    return obj;
+}
+/** Os textos que o motor lê como cena: prompt e parentes, fora o negativo. */
+function textosDeCena(v, chave = "", out = [], fundo = 0) {
+    if (fundo > 6)
+        return out;
+    if (typeof v === "string") {
+        if (/prompt|text|caption|description|scene/i.test(chave) && !/negative/i.test(chave))
+            out.push(v);
+        return out;
+    }
+    if (Array.isArray(v)) {
+        for (const x of v)
+            textosDeCena(x, chave, out, fundo + 1);
+        return out;
+    }
+    if (v && typeof v === "object") {
+        for (const [k, x] of Object.entries(v))
+            textosDeCena(x, k, out, fundo + 1);
+    }
+    return out;
+}
+function conferePisoDeIdade(textos) {
+    const marcas = textos.flatMap((t) => findMinorMarkers(t));
+    if (!marcas.length)
+        return;
+    const citados = [...new Set(marcas.map((m) => `"${m.match}"`))].slice(0, 3).join(", ");
+    throw new Error(`O prompt cita menor de idade (${citados}). A porta da casa não gera isso em motor nenhum: 18 é o piso, 21+ é o padrão. Reescreva com a idade em absoluto ("adult woman, 24") e sem criança, adolescente, teen ou child no texto, mesmo falando de terceiros ou do passado. Se a palavra estava num "NEGATIVE:" dentro do prompt (o passportPrompt da ficha termina com um), mova pro campo negative_prompt do modelo ou tire: no corpo do prompt a maioria dos motores lê o negativo como cena.`);
+}
+function canonico(v) {
+    if (Array.isArray(v))
+        return `[${v.map(canonico).join(",")}]`;
+    if (v && typeof v === "object") {
+        const o = v;
+        return `{${Object.keys(o)
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${canonico(o[k])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(v) ?? "null";
+}
+function hashDoPedido(provedor, modelo, input) {
+    return createHash("sha256").update(`${provedor}\n${modelo}\n${canonico(input)}`).digest("hex");
+}
+// Slug que vai no caminho da URL (fal) ou no corpo (Kie): letras, números,
+// ponto, hífen, sublinhado e barra entre partes. Sem "..", sem esquema, sem
+// barra na frente: o host é fixo e o caminho não passeia.
+const MODELO_VALIDO = /^[a-z0-9][a-z0-9._-]*(\/[a-z0-9][a-z0-9._-]*)*$/i;
+function confereModelo(modelo) {
+    if (!MODELO_VALIDO.test(modelo) || modelo.includes("..")) {
+        throw new Error(`modelo inválido: "${modelo.slice(0, 80)}". Use o slug como está na página do modelo no provedor (ex: 'fal-ai/flux/dev', 'kling/v2-1-standard').`);
+    }
+}
+/** O nome do motor na ficha: sempre com o prefixo do provedor de verdade. */
+function motorDaFicha(provedor, modelo, pedido) {
+    const limpa = (s) => s
+        .toLowerCase()
+        .replace(/^fal-ai\//, "")
+        .replace(/[\s/]+/g, "-")
+        .replace(/[^a-z0-9._-]/g, "")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 80);
+    const base = pedido?.trim() ? limpa(pedido) : limpa(modelo);
+    if (base.startsWith(`${provedor}-`))
+        return base;
+    return `${provedor}-${base || "modelo"}`;
+}
+// ---------------------------------------------------------------------------
+// Os jobs, gravados nesta máquina (nunca no servidor).
+// ---------------------------------------------------------------------------
+function pastaLocal() {
+    return process.env.SAPIENS_MCP_HOME || path.resolve(os.homedir(), ".sapiens-mcp");
+}
+function arquivoDeJobs() {
+    return path.join(pastaLocal(), "pontes-jobs.json");
+}
+function lerJobs() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(arquivoDeJobs(), "utf8"));
+        return Array.isArray(raw?.jobs) ? raw.jobs : [];
+    }
+    catch {
+        return [];
+    }
+}
+function gravarJobs(jobs) {
+    const file = arquivoDeJobs();
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const corpo = semChave(JSON.stringify({ versao: 1, jobs: jobs.slice(-MAX_JOBS_GUARDADOS) }, null, 2));
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, corpo, { encoding: "utf8", mode: 0o600 });
+    fs.renameSync(tmp, file);
+    try {
+        fs.chmodSync(file, 0o600);
+    }
+    catch {
+        // Windows/ACL: chmod pode não aplicar.
+    }
+}
+// Fila de escrita do processo: duas chamadas em paralelo não se atropelam no
+// arquivo (ler-mudar-gravar sem trava perde o job de uma delas).
+let filaDeEscrita = Promise.resolve();
+function comTrava(fn) {
+    const vez = filaDeEscrita.then(fn, fn);
+    filaDeEscrita = vez.catch(() => undefined);
+    return vez;
+}
+function salvarJob(job) {
+    return comTrava(() => {
+        const jobs = lerJobs().filter((j) => j.id !== job.id);
+        jobs.push({ ...job, atualizadoEm: Date.now() });
+        gravarJobs(jobs);
+    });
+}
+function novoId() {
+    return `pj_${randomBytes(6).toString("hex")}`;
+}
+const EXT_ACEITA = /\.(png|jpe?g|webp|mp4|mov)(\?|#|$)/i;
+function detalheDoErro(json) {
+    const d = json?.detail ?? json?.error?.message ?? json?.error ?? json?.message ?? json?.msg;
+    if (typeof d === "string")
+        return d.slice(0, 400);
+    if (Array.isArray(d))
+        return d.map((x) => x?.msg ?? JSON.stringify(x)).join("; ").slice(0, 400);
+    if (d)
+        return JSON.stringify(d).slice(0, 400);
+    return "";
+}
+/** As URLs de mídia que o provedor devolveu, na ordem, sem repetir. */
+function urlsDeMidia(v, out = [], fundo = 0) {
+    if (fundo > 6 || out.length >= MAX_PECAS_POR_JOB * 2)
+        return out;
+    if (Array.isArray(v)) {
+        for (const x of v)
+            urlsDeMidia(x, out, fundo + 1);
+        return out;
+    }
+    if (v && typeof v === "object") {
+        const o = v;
+        if (typeof o.url === "string" && o.url.startsWith("https://")) {
+            const tipo = typeof o.content_type === "string" ? o.content_type : "";
+            if ((/^(image|video)\//.test(tipo) || EXT_ACEITA.test(o.url)) && !out.includes(o.url))
+                out.push(o.url);
+        }
+        for (const [k, x] of Object.entries(o))
+            if (k !== "url")
+                urlsDeMidia(x, out, fundo + 1);
+    }
+    return out;
+}
+// --- fal: fila em queue.fal.run ---
+const FAL_FILA = "https://queue.fal.run";
+/** Só manda a chave de volta pro host da fila da fal, nunca pra URL de outro host. */
+function urlDaFilaFal(u) {
+    if (typeof u !== "string")
+        return null;
+    try {
+        const url = new URL(u);
+        return url.protocol === "https:" && url.hostname === "queue.fal.run" ? url.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function falEnviar(chave, modelo, input) {
+    const res = await fetch(`${FAL_FILA}/${modelo}`, {
+        method: "POST",
+        headers: { Authorization: `Key ${chave}`, "Content-Type": "application/json" },
+        body: JSON.stringify(input),
+        signal: AbortSignal.timeout(30_000),
+    });
+    const json = await res.json().catch(() => null);
+    if (!res.ok || typeof json?.request_id !== "string") {
+        throw new Error(`A fal recusou o pedido (HTTP ${res.status}): ${detalheDoErro(json) || "resposta sem detalhe"}. ` +
+            (res.ok
+                ? "Confira no painel da fal se o pedido entrou antes de repetir."
+                : "Nada entrou na fila."));
+    }
+    // A fila da fal responde com as URLs de status e resultado; quando faltam,
+    // o caminho é <dono>/<app>/requests/<id> (o resto do slug não entra).
+    const app = modelo.split("/").slice(0, 2).join("/");
+    const base = `${FAL_FILA}/${app}/requests/${json.request_id}`;
+    return {
+        requestId: json.request_id,
+        statusUrl: urlDaFilaFal(json.status_url) ?? `${base}/status`,
+        responseUrl: urlDaFilaFal(json.response_url) ?? base,
+    };
+}
+async function falLer(chave, job) {
+    const aindaNao = { estado: job.estado === "rodando" ? "rodando" : "fila" };
+    const statusUrl = urlDaFilaFal(job.statusUrl);
+    const responseUrl = urlDaFilaFal(job.responseUrl);
+    if (!statusUrl || !responseUrl)
+        return { estado: "falhou", erro: "job sem endereço de consulta da fal" };
+    let res;
+    try {
+        res = await fetch(statusUrl, {
+            headers: { Authorization: `Key ${chave}` },
+            signal: AbortSignal.timeout(20_000),
+        });
+    }
+    catch {
+        return aindaNao; // consulta que falha não é geração que falhou
+    }
+    if (!res.ok)
+        return aindaNao;
+    const st = await res.json().catch(() => null);
+    if (st?.status === "IN_QUEUE")
+        return { estado: "fila" };
+    if (st?.status !== "COMPLETED")
+        return { estado: "rodando" };
+    if (st?.error) {
+        return { estado: "falhou", erro: `${st.error_type ? `${st.error_type}: ` : ""}${String(st.error).slice(0, 400)}` };
+    }
+    let out;
+    try {
+        out = await fetch(responseUrl, {
+            headers: { Authorization: `Key ${chave}` },
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch {
+        return { estado: "rodando" };
+    }
+    const json = await out.json().catch(() => null);
+    if (out.status >= 500)
+        return { estado: "rodando" };
+    if (!out.ok) {
+        return { estado: "falhou", erro: `HTTP ${out.status}: ${detalheDoErro(json) || "sem detalhe"}` };
+    }
+    const urls = urlsDeMidia(json);
+    if (!urls.length)
+        return { estado: "falhou", erro: "a fal terminou mas não devolveu arquivo de imagem ou vídeo" };
+    return { estado: "pronto", urls, custo: "pago na fal com a sua chave" };
+}
+// --- Kie: createTask + recordInfo, o mesmo par pro Market inteiro ---
+const KIE_JOBS = "https://api.kie.ai/api/v1/jobs";
+/** 1 crédito Kie = US$ 0,005 (a unidade da tabela deles). */
+const KIE_CREDITO_USD = 0.005;
+async function kieEnviar(chave, modelo, input) {
+    const res = await fetch(`${KIE_JOBS}/createTask`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${chave}`, "Content-Type": "application/json" },
+        body: JSON.stringify({ model: modelo, input }),
+        signal: AbortSignal.timeout(30_000),
+    });
+    const json = await res.json().catch(() => null);
+    // A armadilha da Kie: HTTP 200 não é sucesso, o veredito é o `code` do corpo
+    // (422 modelo inexistente, 500 campo faltando, 401 chave).
+    if (json?.code !== 200 || typeof json?.data?.taskId !== "string") {
+        throw new Error(`A Kie recusou o pedido (código ${json?.code ?? res.status}): ${json?.msg || "resposta sem detalhe"}. Nada entrou na fila.`);
+    }
+    return { requestId: json.data.taskId };
+}
+async function kieLer(chave, job) {
+    const aindaNao = { estado: job.estado === "rodando" ? "rodando" : "fila" };
+    let res;
+    try {
+        res = await fetch(`${KIE_JOBS}/recordInfo?taskId=${encodeURIComponent(job.requestId)}`, {
+            headers: { Authorization: `Bearer ${chave}` },
+            signal: AbortSignal.timeout(20_000),
+        });
+    }
+    catch {
+        return aindaNao;
+    }
+    if (!res.ok)
+        return aindaNao;
+    const json = await res.json().catch(() => null);
+    const d = json?.data;
+    if (!d)
+        return aindaNao;
+    if (d.state === "success") {
+        // `resultJson` é STRING com JSON dentro.
+        let urls = [];
+        try {
+            const parsed = typeof d.resultJson === "string" ? JSON.parse(d.resultJson) : d.resultJson;
+            if (Array.isArray(parsed?.resultUrls)) {
+                urls = parsed.resultUrls.filter((u) => typeof u === "string" && u.startsWith("https://"));
+            }
+        }
+        catch {
+            // cai no "sem arquivo" abaixo
+        }
+        if (!urls.length)
+            return { estado: "falhou", erro: "a Kie terminou mas não devolveu arquivo" };
+        const creditos = typeof d.creditsConsumed === "number" ? d.creditsConsumed : undefined;
+        return {
+            estado: "pronto",
+            urls,
+            custo: creditos != null
+                ? `${creditos} créditos Kie (~US$ ${(creditos * KIE_CREDITO_USD).toFixed(2)})`
+                : "pago na Kie com a sua chave",
+        };
+    }
+    if (d.state === "fail") {
+        return { estado: "falhou", erro: String(d.failMsg || d.failCode || "a Kie marcou falha sem motivo").slice(0, 400) };
+    }
+    return { estado: d.state === "generating" ? "rodando" : "fila" };
+}
+// ---------------------------------------------------------------------------
+// O laço: consultar, e quando pronto, trazer pro acervo.
+// ---------------------------------------------------------------------------
+function dormir(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+function aplicar(job, leitura) {
+    if (leitura.estado === "pronto") {
+        return {
+            ...job,
+            estado: "pronto",
+            resultUrls: leitura.urls.slice(0, MAX_PECAS_POR_JOB),
+            custo: job.ficha.externalCost ?? leitura.custo,
+            erro: undefined,
+        };
+    }
+    if (leitura.estado === "falhou")
+        return { ...job, estado: "falhou", erro: leitura.erro };
+    return { ...job, estado: leitura.estado };
+}
+async function ingerirPecas(job) {
+    const pecas = [...(job.pecas ?? [])];
+    for (const url of job.resultUrls ?? []) {
+        const ja = pecas.find((p) => p.url === url);
+        if (ja?.imageId)
+            continue;
+        try {
+            const r = await gallery({
+                action: "ingest",
+                sourceUrl: url,
+                externalEngine: job.ficha.externalEngine,
+                prompt: job.ficha.prompt,
+                externalCost: job.custo,
+                characterId: job.ficha.characterId,
+                characterIds: job.ficha.characterIds,
+                referenceImageIds: job.ficha.referenceImageIds,
+                aspectRatio: job.ficha.aspectRatio,
+                size: job.ficha.size,
+                unfiltered: job.ficha.unfiltered,
+                skills: job.ficha.skills,
+            });
+            const peca = {
+                url,
+                imageId: r?.imageId ? String(r.imageId) : undefined,
+                acervoUrl: r?.acervoUrl,
+                adulta: r?.adulta ? true : undefined,
+            };
+            if (ja)
+                Object.assign(ja, peca, { erro: undefined });
+            else
+                pecas.push(peca);
+        }
+        catch (e) {
+            // O ingest é idempotente pela URL: o próximo status tenta de novo sem duplicar.
+            const erro = describeConvexError(e);
+            if (ja)
+                ja.erro = erro;
+            else
+                pecas.push({ url, erro });
+        }
+    }
+    const todas = (job.resultUrls ?? []).every((u) => pecas.some((p) => p.url === u && p.imageId));
+    return { ...job, pecas, estado: todas ? "ingerido" : "pronto" };
+}
+async function avancar(job, segundos) {
+    const inicio = Date.now();
+    const prazo = inicio + Math.max(0, Math.min(segundos, ESPERA_MAX_S)) * 1000;
+    const intervalo = job.provedor === "kie" ? 3000 : 2500;
+    let atual = job;
+    for (;;) {
+        if (atual.estado === "fila" || atual.estado === "rodando") {
+            const chave = chaveDo(atual.provedor);
+            const leitura = atual.provedor === "fal" ? await falLer(chave, atual) : await kieLer(chave, atual);
+            atual = aplicar(atual, leitura);
+            await salvarJob(atual);
+        }
+        if (atual.estado === "pronto" && atual.ingerir && Date.now() - inicio < INGEST_SO_ATE_MS) {
+            atual = await ingerirPecas(atual);
+            await salvarJob(atual);
+            return atual;
+        }
+        if (atual.estado !== "fila" && atual.estado !== "rodando")
+            return atual;
+        if (Date.now() + intervalo > prazo)
+            return atual;
+        await dormir(intervalo);
+    }
+}
+// ---------------------------------------------------------------------------
+// O que volta pro agente.
+// ---------------------------------------------------------------------------
+function proximoPasso(job) {
+    const nome = BALCOES[job.provedor].nome;
+    switch (job.estado) {
+        case "fila":
+        case "rodando":
+            return `Ainda renderizando na ${nome}. Chame sapiens_pontes action=status jobId=${job.id} (aguardarSegundos até ${ESPERA_MAX_S}). NÃO chame gerar de novo: isso cria outro job e cobra outra vez na conta da pessoa.`;
+        case "pronto":
+            if (!job.ingerir) {
+                return "Pronto no provedor, fora do acervo (ingerir=false). A URL do render expira: pra trazer, chame action=status com ingerir=true.";
+            }
+            return job.pecas?.some((p) => p.erro)
+                ? `Gerou, mas a volta pro acervo falhou (ver pecas[].erro). Chame action=status jobId=${job.id} de novo: o ingest é idempotente, não duplica.`
+                : `Gerou. Chame action=status jobId=${job.id} pra trazer pro acervo (a URL do render expira).`;
+        case "ingerido":
+            return "No acervo, privada e com custo 0 em Sinapses. Mostre com sapiens_gallery action=list (kind=video pra vídeo). Publicar é ato da pessoa (sapiens_gallery action=publish).";
+        case "falhou":
+            return `A ${nome} marcou falha. Confira o painel da ${nome} antes de tentar de novo (a regra de cobrança de job que falha é deles).`;
+    }
+}
+function resumo(job, extra = {}) {
+    return {
+        jobId: job.id,
+        provedor: job.provedor,
+        modelo: job.modelo,
+        estado: job.estado,
+        motor: job.ficha.externalEngine,
+        pecas: job.pecas?.length ? job.pecas : undefined,
+        resultUrls: job.estado === "pronto" ? job.resultUrls : undefined,
+        custo: job.custo,
+        erro: job.erro,
+        chave: `A chave ficou nesta máquina: o pedido saiu daqui direto pra ${BALCOES[job.provedor].nome}. A casa não viu a chave.`,
+        proximoPasso: proximoPasso(job),
+        ...extra,
+    };
+}
+// ---------------------------------------------------------------------------
+// As actions.
+// ---------------------------------------------------------------------------
+async function gerar(args) {
+    const provedor = args.provedor;
+    if (!provedor)
+        throw new Error("action=gerar exige provedor: 'fal' ou 'kie'.");
+    const modelo = args.modelo?.trim();
+    if (!modelo) {
+        throw new Error("action=gerar exige modelo: o slug do modelo no provedor, igual à página dele.");
+    }
+    confereModelo(modelo);
+    const chave = chaveDo(provedor);
+    const input = lerInput(args.input);
+    confereSemChaveNoPedido(input, args.prompt);
+    conferePisoDeIdade([...(args.prompt ? [args.prompt] : []), ...textosDeCena(input)]);
+    const ingerir = args.ingerir ?? true;
+    if (ingerir) {
+        try {
+            getSessionToken();
+        }
+        catch {
+            throw new Error("Pra peça voltar pro acervo, a conta Sapiens precisa estar conectada neste MCP (sapiens_meta action=login). Sem conta, mande ingerir=false: a peça fica só no provedor.");
+        }
+    }
+    const hash = hashDoPedido(provedor, modelo, input);
+    if (!args.forcar) {
+        const igual = lerJobs()
+            .reverse()
+            .find((j) => j.hash === hash && j.estado !== "falhou" && Date.now() - j.criadoEm < JANELA_REPETIDO_MS);
+        if (igual) {
+            if (args.ingerir === true)
+                igual.ingerir = true;
+            const atual = await avancar(igual, Math.min(args.aguardarSegundos ?? 0, ESPERA_MAX_S));
+            return resumo(atual, {
+                repetido: true,
+                aviso: "Esse mesmo pedido já tinha ido pro provedor há menos de 30 minutos: devolvi o job que existe em vez de criar outro, pra não cobrar duas vezes. Pra gerar de novo de propósito, mande forcar=true.",
+            });
+        }
+    }
+    const promptDaFicha = args.prompt?.trim() ||
+        (typeof input.prompt === "string" && input.prompt.trim() ? input.prompt : JSON.stringify(input).slice(0, 4000));
+    const enviado = provedor === "fal" ? await falEnviar(chave, modelo, input) : await kieEnviar(chave, modelo, input);
+    const agora = Date.now();
+    const job = {
+        id: novoId(),
+        provedor,
+        modelo,
+        hash,
+        criadoEm: agora,
+        atualizadoEm: agora,
+        estado: "fila",
+        ...enviado,
+        ingerir,
+        ficha: {
+            externalEngine: motorDaFicha(provedor, modelo, args.externalEngine),
+            prompt: promptDaFicha,
+            externalCost: args.externalCost,
+            characterId: args.characterId,
+            characterIds: args.characterIds,
+            referenceImageIds: args.referenceImageIds,
+            aspectRatio: args.aspectRatio ?? (typeof input.aspect_ratio === "string" ? input.aspect_ratio : undefined),
+            size: args.size ?? (typeof input.resolution === "string" ? input.resolution : undefined),
+            unfiltered: args.unfiltered,
+            skills: args.skills,
+        },
+    };
+    // Gravado ANTES de esperar: se o cliente desistir no meio, o job continua
+    // aqui e o status termina, em vez de alguém gerar (e pagar) de novo.
+    await salvarJob(job);
+    const atual = await avancar(job, args.aguardarSegundos ?? ESPERA_PADRAO_GERAR_S);
+    return resumo(atual);
+}
+async function status(args) {
+    if (!args.jobId)
+        throw new Error("action=status exige jobId (o pj_... que o gerar devolveu; action=jobs lista).");
+    const job = lerJobs().find((j) => j.id === args.jobId);
+    if (!job) {
+        throw new Error(`Job ${args.jobId} não está nesta máquina. Os jobs moram em ${arquivoDeJobs()} do computador que gerou; liste com action=jobs.`);
+    }
+    if (args.ingerir === true)
+        job.ingerir = true;
+    const atual = await avancar(job, args.aguardarSegundos ?? ESPERA_PADRAO_STATUS_S);
+    return resumo(atual);
+}
+function balcoes() {
+    return {
+        regra: "A chave mora no env do config do seu cliente MCP, nesta máquina, e sai daqui só pro provedor. A casa não recebe, não guarda e não vê. Gerar com a sua chave custa zero em Sinapses: você paga o preço do provedor, sem margem da casa.",
+        balcoes: Object.keys(BALCOES).map((k) => {
+            const v = process.env[BALCOES[k].envVar]?.trim();
+            return {
+                provedor: k,
+                nome: BALCOES[k].nome,
+                variavel: BALCOES[k].envVar,
+                configurada: Boolean(v && v.length >= 8),
+            };
+        }),
+        comoConfigurar: `No config do cliente MCP, no bloco do sapiens: "env": { "FAL_KEY": "<sua chave da fal>", "KIE_API_KEY": "<sua chave da Kie>" }. Depois reinicie o cliente. Passo a passo por cliente: ${ENDERECO_SUAS_CHAVES}`,
+        ondeAcharOModelo: "fal: o id do endpoint na página do modelo em fal.ai/models (ex: 'fal-ai/flux/dev'). Kie: o 'model' da página do modelo no Market da Kie. O input é o corpo que a mesma página descreve.",
+        outrosBalcoes: "Sogni, Krea, Magnific, WaveSpeed, Replicate e a própria placa seguem pelo seu harness + sapiens_gallery action=ingest (catálogo em sapiens_meta action=pontes).",
+    };
+}
+function jobs(args) {
+    const lista = lerJobs().slice(-(args.limit ?? 10)).reverse();
+    return {
+        arquivo: arquivoDeJobs(),
+        count: lista.length,
+        jobs: lista.map((j) => ({
+            jobId: j.id,
+            provedor: j.provedor,
+            modelo: j.modelo,
+            estado: j.estado,
+            criadoEm: new Date(j.criadoEm).toISOString(),
+            pecas: j.pecas?.filter((p) => p.imageId).map((p) => p.imageId),
+            custo: j.custo,
+        })),
+    };
+}
+async function pontesInterno(args) {
+    if (isRemoteContext()) {
+        throw new Error("sapiens_pontes só roda no MCP instalado (sapiens-mcp no seu computador): a chave mora na sua máquina e o conector remoto não recebe chave nenhuma. Aqui, gere em Sinapse (sapiens_image, sapiens_video) ou instale o MCP local: https://www.sapiensinteticos.com/conectar-claude");
+    }
+    switch (args.action) {
+        case "balcoes":
+            return balcoes();
+        case "gerar":
+            return gerar(args);
+        case "status":
+            return status(args);
+        case "jobs":
+            return jobs(args);
+    }
+}
+export async function pontes(args) {
+    try {
+        return limpo(await pontesInterno(args));
+    }
+    catch (e) {
+        throw new Error(semChave(describeConvexError(e)));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sapiens-mcp",
-  "version": "1.78.1",
+  "version": "1.79.0",
   "mcpName": "com.sapiensinteticos/sapiens",
   "description": "MCP server pra operar o Sapiens Sintéticos (sapiensinteticos.com) pelo Claude Code: gerar imagem, escrever artigo, voz, música e mais, na sua conta. Login pelo código de sapiensinteticos.com/conectar-claude.",
   "type": "module",
@@ -36,7 +36,7 @@
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "pretest": "npm run build",
-    "test": "node --test --test-force-exit test/unit.test.mjs test/server.test.mjs test/remote.test.mjs test/remote-protect.test.mjs",
+    "test": "node --test --test-force-exit test/unit.test.mjs test/server.test.mjs test/remote.test.mjs test/remote-protect.test.mjs test/pontes.test.mjs",
     "prepublishOnly": "npm run build"
   },
   "repository": {