sapiens-mcp 1.29.0 → 1.29.2

package/dist/convexClient.js

@@ -239,10 +239,14 @@ export function describeConvexError(e) {
 // Teto de tempo por chamada ao Convex. O ConvexHttpClient não aceita
 // AbortSignal em query/mutation/action, então o bound prático é um race contra
 // um timer. Sem isto, um backend pendurado deixa a chamada MCP presa até o
-// timeout do host, sem erro claro — ruim numa sessão que acabou de mandar
+// timeout do host, sem erro claro, ruim numa sessão que acabou de mandar
 // debitar Sinapses e não sabe se caiu. NÃO há retry/backoff de propósito:
 // chamadas não-idempotentes (cobrança) não podem re-disparar às cegas.
-const CONVEX_TIMEOUT_MS = Number(process.env.SAPIENS_CONVEX_TIMEOUT_MS) || 30000;
+// Default 120s (era 30s): geração síncrona (imagem pesada, artigo, mega-gráfico,
+// carrossel) leva de 30 a 90s e estourava o teto de 30s, voltando 'Timeout' pro
+// cliente MESMO tendo gerado e COBRADO. 120s cobre esses casos; render de vídeo
+// (minutos) ainda precisa do fluxo assíncrono. Override por env pra outro teto.
+const CONVEX_TIMEOUT_MS = Number(process.env.SAPIENS_CONVEX_TIMEOUT_MS) || 120000;
 function withTimeout(p, label) {
     let timer;
     const timeout = new Promise((_, reject) => {

package/dist/index.js

@@ -36,12 +36,12 @@ import { describeConvexError } from "./convexClient.js";
 import { MCP_VERSION } from "./version.js";
 const TOOLS = {
     sapiens_pipeline: {
-        description: "CRUD do content pipeline Sapiens (sources/productions/publishables). Sub-actions: list_sources, list_articles (use includeDrafts pra incluir drafts; onlyAvailable pra esconder os já virados em source), get_source, get_production, list_versions, add_article_as_source, create_draft_article_and_source (seed), create_production (sourceId+format → productionId draft), update_production (substitui payload, opcionalmente muda status), finalize_production (cria publishable v1, v2... com snapshot), remove_production, remove_source, set_source_done, update_source_notes, restore_version (volta payload duma versão antiga), propose_mega_grafico_plan (granular: só gera plano via Gemini, devolve fullPrompt+spec), run_mega_grafico_full (ONE-SHOT, recomendado: cria production+propõe plano+gera imagem+aplica selo Sapiens+finaliza publishable numa chamada só), generate_carousel (gera um carrossel editorial standalone a partir de brief OU articleId — 7-9 slides na voz Sapiens + imagens do banco; devolve id + url do editor pro humano abrir, ajustar e exportar; admin-only, cobra Sinapses, reembolsa se falhar). Pra mega_grafico, SEMPRE prefira run_mega_grafico_full em vez de sequenciar manualmente — menos drift, idempotente (passa productionId pra reusar). OBRIGATÓRIO perguntar ao user antes se withHelen=true (cartoon Helen interage com tema, ~15-25% do poster) ou false (poster 100% diagramático). Custo ~900-1000 sinapses por geração. Use skipFinalize=true se quiser deixar production em 'ready' pro admin revisar antes de publishable. Payload livre por formato — chame sapiens_meta action=formats pra ver schemas sugeridos.",
+        description: "CRUD do content pipeline Sapiens (sources/productions/publishables). Sub-actions: list_sources, list_articles (use includeDrafts pra incluir drafts; onlyAvailable pra esconder os já virados em source), get_source, get_production, list_versions, add_article_as_source, create_draft_article_and_source (seed), create_production (sourceId+format → productionId draft), update_production (substitui payload, opcionalmente muda status), finalize_production (cria publishable v1, v2... com snapshot), remove_production, remove_source, set_source_done, update_source_notes, restore_version (volta payload duma versão antiga), propose_mega_grafico_plan (granular: só gera plano via Gemini, devolve fullPrompt+spec), run_mega_grafico_full (ONE-SHOT, recomendado: cria production+propõe plano+gera imagem+aplica selo Sapiens+finaliza publishable numa chamada só), generate_carousel (gera um carrossel editorial standalone a partir de brief OU articleId — 7-9 slides na voz Sapiens + imagens do banco; devolve id + url do editor pro humano abrir, ajustar e exportar; admin-only, cobra Sinapses, reembolsa se falhar). Pra mega_grafico, SEMPRE prefira run_mega_grafico_full em vez de sequenciar manualmente (menos drift). Idempotente só na production (passa productionId pra reusar a MESMA row), mas cada run RE-GERA a imagem e cobra de novo (~900 Sinapses): não é grátis re-rodar. OBRIGATÓRIO perguntar ao user antes se withHelen=true (cartoon Helen interage com tema, ~15-25% do poster) ou false (poster 100% diagramático). Custo ~900-1000 sinapses por geração. run_mega_grafico_full e generate_carousel são SÍNCRONAS e pesadas (Gemini + imagem): podem passar do teto de ~120s do cliente e voltar 'Timeout' MESMO tendo criado a production e cobrado, então cheque /dashboard/admin/content antes de repetir. Use skipFinalize=true se quiser deixar production em 'ready' pro admin revisar antes de publishable. Payload livre por formato — chame sapiens_meta action=formats pra ver schemas sugeridos.",
         schema: pipelineSchema,
         handler: pipeline,
     },
     sapiens_image: {
-        description: "Operações de imagem via Sapiens (Gemini, Azure gpt-image-2, Grok, Veo). Sub-actions: 'generate' (gera imagem completa imediato — prompt+model+aspectRatio+size; suporta mode=edit/variation e MULTI-REFERÊNCIA: combine até 4 imagens como referência numa geração só, igual ao modal 'Selecionar Referência' do web — via referenceImageUrls (sua galeria + Acervo + personagens públicos de sapiens_character) e/ou sourceImageIds (ids da sua galeria); refs valem pros modelos robustos nano-banana-2/gpt-image-2-*/grok-2-image*), 'request_generation' (v1.7, cria APENAS row pendente em generatedImages + debita créditos — pra modelos sapiens-video-* ANTES de sapiens_shorts/sapiens_video; whitelist, rate limit 3/min), 'compose' (v1.8, combina persona+screen via Gemini pra app-demo Shorts; 25 sinapses, rate limit 10/min). generate=image one-shot, request_generation=criar row video, compose=montar start frame app-demo. TEMPLATE (v1.17): passe templateSlug numa generate pra usar um super-prompt travado da casa — o `prompt` vira só a CENA (quem + pose + objeto-conceito) e o template embrulha estilo+fundo+enquadramento+ref de traço. 'retrato-sapiens-v1' = retrato editorial cartoon de um personagem no grid verde Sapiens (mesma 'mão' dos artigos); sem ref própria, injeta a Helen como âncora de traço (passar referenceImageUrls troca quem aparece). Mutuamente exclusivo com brandSlug.",
+        description: "Operações de imagem via Sapiens (Gemini, Azure gpt-image-2, Grok, Veo). Sub-actions: 'generate' (gera imagem completa imediato — prompt+model+aspectRatio+size; suporta mode=edit/variation e MULTI-REFERÊNCIA: combine até 4 imagens como referência numa geração só, igual ao modal 'Selecionar Referência' do web — via referenceImageUrls (sua galeria + Acervo + personagens públicos de sapiens_character) e/ou sourceImageIds (ids da sua galeria); refs valem pros modelos robustos nano-banana-2/gpt-image-2-*/grok-2-image*), 'request_generation' (v1.7, cria APENAS row pendente em generatedImages + debita créditos — pra modelos sapiens-video-* ANTES de sapiens_shorts/sapiens_video; whitelist, rate limit 3/min), 'compose' (v1.8, combina persona+screen via Gemini pra app-demo Shorts; 25 sinapses, rate limit 10/min). generate=image one-shot, request_generation=criar row video, compose=montar start frame app-demo. TEMPLATE (v1.17): passe templateSlug numa generate pra usar um super-prompt travado da casa — o `prompt` vira só a CENA (quem + pose + objeto-conceito) e o template embrulha estilo+fundo+enquadramento+ref de traço. 'retrato-sapiens-v1' = retrato editorial cartoon de um personagem no grid verde Sapiens (mesma 'mão' dos artigos); sem ref própria, injeta a Helen como âncora de traço (passar referenceImageUrls troca quem aparece). Mutuamente exclusivo com brandSlug. Sub-action 'models' (sem custo, sem login): lista o catálogo vivo (modelos ativos + preço atual com override admin + maxResolution + se aceita referência) pra descobrir modelo/preço em vez de chutar. NOTA: generate é SÍNCRONA e cobra ao concluir; modelo pesado (Pro, gpt-image-2-high, Grok quality, 2K/4K) pode estourar o teto de ~120s do cliente e voltar 'Timeout' MESMO tendo gerado e cobrado, então na dúvida cheque sapiens_gallery action=list antes de repetir (evita cobrança dupla).",
         schema: imageSchema,
         handler: image,
     },
@@ -71,7 +71,7 @@ const TOOLS = {
         handler: article,
     },
     sapiens_write: {
-        description: "Artigos self-serve do PRÓPRIO usuário (qualquer conta logada, não só admin) — espaço pessoal, aparece em /u/<username>, NÃO é o blog editorial. Sub-actions: generate (gera 1 artigo na voz Sapiens a partir de brief livre, ou reescrevendo um artigo publicado/texto teu; custa 400 Sinapses, reembolsa se falhar; salva como rascunho. Capa: por padrão gera uma capa-cortesia grátis; se você JÁ tem a imagem (gerou via sapiens_image, ou o artigo é sobre ela), passe coverImageId (id da tua galeria) ou coverImageUrl (host Sapiens) pra ELA virar a capa em vez da cortesia), list (teus artigos), get (1 artigo teu por id, corpo completo), update (edita title/content/excerpt/tldr), publish (publish=true publica no teu perfil, false volta pra rascunho). Identidade vem do sessionToken; cobra as Sinapses do dono do token. Pra blog editorial curado (owner-only) use sapiens_article.",
+        description: "Artigos self-serve do PRÓPRIO usuário (qualquer conta logada, não só admin) — espaço pessoal, aparece em /u/<username>, NÃO é o blog editorial. Sub-actions: generate (gera 1 artigo na voz Sapiens a partir de brief livre, ou reescrevendo um artigo publicado/texto teu; custa 400 Sinapses, reembolsa se falhar; salva como rascunho. Capa: por padrão gera uma capa-cortesia grátis; se você JÁ tem a imagem (gerou via sapiens_image, ou o artigo é sobre ela), passe coverImageId (id da tua galeria) ou coverImageUrl (host Sapiens) pra ELA virar a capa em vez da cortesia), list (teus artigos), get (1 artigo teu por id, corpo completo), update (edita title/content/excerpt/tldr), publish (publish=true publica no teu perfil, false volta pra rascunho). Identidade vem do sessionToken; cobra as Sinapses do dono do token. Pra blog editorial curado (owner-only) use sapiens_article. NOTA (generate): é SÍNCRONA (texto + capa) e pode passar do teto de ~120s do cliente, voltando 'Timeout' MESMO tendo gerado e cobrado 400 (o artigo fica salvo como rascunho). Como não tem idempotência, repetir às cegas gera um 2º rascunho e cobra 400 de novo: cheque sapiens_write action=list antes de repetir.",
         schema: writeSchema,
         handler: write,
     },
@@ -106,12 +106,12 @@ const TOOLS = {
         handler: musicator,
     },
     sapiens_shorts: {
-        description: "Sapiens Shorts — render vertical 9:16 via VEO com brief structured (v1.5, admin-only). Sub-action: render. Args: imageId (persona pré-existente em generatedImages, descubra via sapiens_gallery), styleId ('ugc'/'unboxing'/'app-demo'/'reflexao'), brief (product+hook+shots+vibe), references opcionais. Retorna {success, url} (URL VEO com expiração curta — baixe logo). Pré-requisito: o imageId precisa ter row em generatedImages do user da sessão e cost definido. Pra criar row, use a UI primeiro (v1.6 vai cobrir requestGeneration via MCP).",
+        description: "Sapiens Shorts — render vertical 9:16 via VEO com brief structured (v1.5, admin-only). Sub-action: render. Args: imageId (persona pré-existente em generatedImages, descubra via sapiens_gallery), styleId ('ugc'/'unboxing'/'app-demo'/'reflexao'), brief (product+hook+shots+vibe), references opcionais. render é ASSÍNCRONO: volta na hora com {imageId, status:'rendering', url:null}, e você acompanha com sapiens_video action=status imageId=<id> até status='completed' (traz a url VEO, expiração curta, baixe logo) ou 'error'. Pré-requisito: o imageId precisa ter row em generatedImages do user da sessão e cost definido. Pra criar row, use a UI primeiro (v1.6 vai cobrir requestGeneration via MCP).",
         schema: shortsSchema,
         handler: shorts,
     },
     sapiens_video: {
-        description: "Sapiens Video — gera vídeo (qualquer membro logado; vídeo é caro, cobra as Sinapses da sua conta). Sub-action 'create' (recomendada): escolhe modelo + config e gera num call (cria a row + renderiza). Modelos: 'sapiens-video-seedance' (Seedance 2.0, cena+áudio nativo, 4-15s, 480/720/1080p, t2v/i2v), 'sapiens-video-kling' (Kling 3.0 Pro, anima imagem, 3-15s, sound opcional, i2v/t2v), 'sapiens-video-wan' (WAN 2.5, imagem que fala/canta com áudio+lip-sync, 5/10s, i2v), 'sapiens-video-kling-motion' (Motion transfer: passa o movimento de um vídeo pra uma imagem, PRECISA de pessoa com tronco visível na imagem E no vídeo), 'sapiens-video-shot-mimic' (Shot Mimic: recria o plano/câmera/cortes de um vídeo de referência como cena nova), 'sapiens-video-omni' (Gemini Omni: texto vira vídeo 10s 720p com áudio nativo; NÃO aceita mídia do user, ignora references/durationSec/resolution; editOfImageId aponta um vídeo Omni seu e o prompt edita a MESMA cena, preservando câmera e ambiente), 'sapiens-video-lite/fast/quality' (Veo 3.1). Args create: model, prompt, durationSec, resolution ('480p'/'720p'/'1080p'), audio, aspectRatio. FRAME INICIAL/FINAL POR REFERÊNCIA (recomendado): startImageId/endImageId (id da sua galeria) ou startImageUrl/endImageUrl (url de galeria/Acervo/personagem) — resolvidos server-side igual à imagem, descubra via sapiens_reference. Alternativa base64: references (role 'start'=imagem i2v, 'end'=frame final, 'driving'=vídeo de movimento do Motion). Suporte a frame final varia por modelo. Custo server-side por config. Sub-action 'generate' (legado): renderiza um imageId de vídeo já criado no site. Retorna {success, url, imageId, cost}. VITRINE (sem custo): sub-action 'demos' lista os SEUS demo films (kind=demo do Estúdio de Vídeo) com slug + estado de vitrine; sub-action 'showcase' põe/tira um demo (por slug) do mini-cinema da /conectar-claude, com showcaseTag (chip de capacidade) e showcaseOrder (ordem asc). Fluxo: 'demos' pra achar o slug, depois 'showcase' com showcase=true. Só entra na vitrine pública se for a conta da casa.",
+        description: "Sapiens Video — gera vídeo (qualquer membro logado; vídeo é caro, cobra as Sinapses da sua conta). Sub-action 'create' (recomendada): escolhe modelo + config e gera num call (cria a row + renderiza). Modelos: 'sapiens-video-seedance' (Seedance 2.0, cena+áudio nativo, 4-15s, 480/720/1080p, t2v/i2v), 'sapiens-video-kling' (Kling 3.0 Pro, anima imagem, 3-15s, sound opcional, i2v/t2v), 'sapiens-video-wan' (WAN 2.5, imagem que fala/canta com áudio+lip-sync, 5/10s, i2v), 'sapiens-video-kling-motion' (Motion transfer: passa o movimento de um vídeo pra uma imagem, PRECISA de pessoa com tronco visível na imagem E no vídeo), 'sapiens-video-shot-mimic' (Shot Mimic: recria o plano/câmera/cortes de um vídeo de referência como cena nova), 'sapiens-video-omni' (Gemini Omni: texto vira vídeo 10s 720p com áudio nativo; NÃO aceita mídia do user, ignora references/durationSec/resolution; editOfImageId aponta um vídeo Omni seu e o prompt edita a MESMA cena, preservando câmera e ambiente), 'sapiens-video-lite/fast/quality' (Veo 3.1). Args create: model, prompt, durationSec, resolution ('480p'/'720p'/'1080p'), audio, aspectRatio. FRAME INICIAL/FINAL POR REFERÊNCIA (recomendado): startImageId/endImageId (id da sua galeria) ou startImageUrl/endImageUrl (url de galeria/Acervo/personagem) — resolvidos server-side igual à imagem, descubra via sapiens_reference. Alternativa base64: references (role 'start'=imagem i2v, 'end'=frame final, 'driving'=vídeo de movimento do Motion). Suporte a frame final varia por modelo. Custo server-side por config. Sub-action 'generate' (legado): renderiza um imageId de vídeo já criado no site. Retorna {success, url, imageId, cost}. VITRINE (sem custo): sub-action 'demos' lista os SEUS demo films (kind=demo do Estúdio de Vídeo) com slug + estado de vitrine; sub-action 'showcase' põe/tira um demo (por slug) do mini-cinema da /conectar-claude, com showcaseTag (chip de capacidade) e showcaseOrder (ordem asc). Fluxo: 'demos' pra achar o slug, depois 'showcase' com showcase=true. Só entra na vitrine pública se for a conta da casa. create é ASSÍNCRONA: cria o row, debita e volta NA HORA com {imageId, status:'rendering', cost} (não espera o render, que leva de segundos a minutos). Acompanhe com a sub-action 'status' (imageId) até status='completed' (traz a url) ou 'error'/'blocked'. NÃO chame create de novo enquanto renderiza (cria outro vídeo e cobra de novo); falha de provider refunda sozinha. Sub-action 'models' (sem custo, sem login): lista os modelos de vídeo ativos + preço-piso + config (durações/resoluções) + disponibilidade (Omni depende de env).",
         schema: videoSchema,
         handler: video,
     },
@@ -207,7 +207,7 @@ Música (sapiens_musicator) é fluxo de 4 passos, EM ORDEM:
 
 Vídeo (sapiens_video) action=create EXIGE 'model': sapiens-video-seedance | kling | wan | kling-motion | lite | fast | quality | omni. Sem model, falha de cara. O 'omni' (Gemini Omni) gera clipe de 10s 720p com áudio nativo a partir de TEXTO (não aceita imagem/vídeo do user, ignora duração/resolução) e EDITA os próprios vídeos: passe editOfImageId com o imageId de um vídeo Omni já gerado e o prompt vira instrução de edição sobre a MESMA cena (troca item/personagem, preserva câmera e ambiente; cada edição debita como geração nova). É o caminho pra variações com continuidade: gera a base uma vez, edita N vezes. Vídeo é o mais caro: confirme com o usuário antes. action=shadows (ADMIN, 200 Sinapses/segundo, refund na falha): passa videoUrl (URL pública) + title (+ durationSec se souber, pra cobrar proporcional; sem ela, flat ~2000) e o servidor extrai a SOMBRA (mapa de profundidade) do vídeo e guarda no Acervo (Corpo) como deepshadow reutilizável (driving pro Shot Mimic/Kling Motion). Vitrine dos demos (sem custo): sapiens_video action=demos lista seus demo films com slug; action=showcase (slug + showcase=true/false + showcaseTag + showcaseOrder) cura o mini-cinema da /conectar-claude. FILMES DA CASA (Estúdio de Vídeo, tela /experimentos/films): são OUTRA coisa, três kinds na tabela videoSpecs: demo (UI clonada + câmera), aula-tour (telas reais + narração) e essay (fita-ensaio abstrata: partícula/tinta vira símbolo, com a logo explodindo no fim; narração da casa OPCIONAL, sai em 16:9 ou 9:16 vertical, e o filme final é limpo, sem rótulos de produção). Eles NÃO são gerados por este MCP: o user monta o spec na tela e um agente local (Claude Code, skill /film) produz o mp4 no repo da casa. Se o user pedir 'fita-ensaio' ou 'demo film' aqui, aponte pra tela e pro agente local.
 
-Imagem (sapiens_image) action=generate: prompt + model + aspectRatio. Referência via referenceImageUrls (galeria/Acervo/personagens) e/ou sourceImageIds. templateSlug aplica um super-prompt travado da casa.
+Imagem (sapiens_image) action=generate: prompt + model + aspectRatio. Referência via referenceImageUrls (galeria/Acervo/personagens) e/ou sourceImageIds. templateSlug aplica um super-prompt travado da casa. PROMPT na regra da casa: full-bleed, sujeito oversized (70%+ do frame), sem "tarot card"/"intimate scale"/moldura/margem. action=models (sem custo, sem login) lista os modelos ativos com o preço atual: consulte quando não tiver certeza do modelo ou do custo.
 
 SEU STUDIO vs geração BASE (não confunda, é o ponto): o usuário tem UM "Meu Studio", único, que o servidor resolve pela SESSÃO. Você NUNCA passa id de studio: é sempre o studio dele. É a identidade configurada dele: marca + personagem-operador + por ferramenta os presets e a "vibe" (o estilo afinado).
 - Criar SEGUINDO o studio (na cara dele): sapiens_image com useStudio=true. O servidor acha o studio e aplica marca + personagem + vibe + presets sozinho (o que você passar explícito vence). O retorno traz studioApplied=true. Use quando ele diz "no meu studio", "na minha marca", "do meu jeito", "como sempre".

package/dist/tools/image.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { httpUrl } from "../schema.js";
-import { convexAction, getSessionToken } from "../convexClient.js";
+import { convexAction, convexQuery, getSessionToken } from "../convexClient.js";
 // IDs canônicos do catálogo (apps/sapiens/convex/shared/imageModels.ts).
 // IDs fora dessa lista caem no fallback e o pricing vira 999. Sempre usar os
 // IDs canônicos.
@@ -29,8 +29,11 @@ const MODELS = [
     "fal-krea2-realism-v2", // Krea-2 + LoRA realismo alt (RudySen), pro A/B · 600 · txt2img
 ];
 export const imageSchema = z.object({
-    action: z.enum(["generate", "request_generation", "compose"]),
-    prompt: z.string().describe("Prompt da imagem. Full-bleed, sujeito oversized."),
+    action: z.enum(["generate", "request_generation", "compose", "models"]),
+    prompt: z
+        .string()
+        .optional()
+        .describe("Prompt da imagem (obrigatório em generate/request_generation). Full-bleed, sujeito oversized."),
     model: z
         .enum(MODELS)
         .optional()
@@ -42,7 +45,7 @@ export const imageSchema = z.object({
     size: z
         .enum(["1K", "2K", "4K"])
         .optional()
-        .describe("Default '1K'. 2K/4K só funcionam em modelos com hasResolutionAdder (nano-banana-max e nano-banana-2), adicionam 100/300 sinapses."),
+        .describe("Default '1K'. Adder de resolução só nos modelos com hasResolutionAdder: nano-banana-max e nano-banana-2 aceitam 2K (+100) e 4K (+300); grok-2-image e grok-2-image-quality aceitam só 2K (+100), sem 4K. Nos demais modelos o size é ignorado (fica em 1K)."),
     styleId: z
         .string()
         .optional()
@@ -108,6 +111,32 @@ export const imageSchema = z.object({
         .describe("Pra action=compose: instrução em EN pro Gemini. Ex: 'Compose a vertical 9:16 photo: persona holding a smartphone facing the camera, the phone screen displaying the provided second image (clearly visible, sharp). Mobile photography aesthetic.'"),
 });
 export async function image(args) {
+    // models: catálogo VIVO dos modelos de imagem (ativos + preço atual com
+    // override admin do systemConfig). READ-ONLY, sem custo e sem login — resolve o
+    // drift da lista hardcoded: o operador descobre modelo/preço/capacidade em vez
+    // de confiar no enum congelado. Antes de exigir sessão de propósito.
+    if (args.action === "models") {
+        const all = await convexQuery("imageModels:listWithOverrides", {});
+        const models = (all ?? [])
+            .filter((m) => m?.isActive)
+            .sort((a, b) => (a.order ?? 99) - (b.order ?? 99))
+            .map((m) => ({
+            id: m.id,
+            label: m.label,
+            priceSinapses: m.effectivePriceSinapses,
+            maxResolution: m.maxResolution ?? "4K",
+            resolutionAdders: m.resolutionAdders,
+            supportsReferences: !!m.supportsReferences,
+            degen: /^(civitai-|wavespeed-|fal-)/.test(String(m.id)),
+            note: m.description ?? null,
+        }));
+        return {
+            count: models.length,
+            default: "nano-banana-2",
+            models,
+            note: "priceSinapses é o base (1K); 2K/4K somam resolutionAdders quando o modelo tem teto pra isso. degen=+18 (gate na galeria). O preço já inclui override admin.",
+        };
+    }
     const sessionToken = getSessionToken();
     // v1.8: compose tem args próprios, validação separada
     if (args.action === "compose") {

package/dist/tools/meta.js

@@ -116,7 +116,7 @@ const FORMAT_GUIDE = {
         },
     },
 };
-// Curadoria do action=start: a PORTA DE ENTRADA, não os 26 tools (despejar tudo
+// Curadoria do action=start: a PORTA DE ENTRADA, não as 29 tools (despejar tudo
 // afoga cliente fraco). 6 primeiros poderes, cada um com 1 frase pronta pra
 // colar. Voz da casa, espelhando a vitrine /conectar-claude (mantido à mão aqui
 // porque o MCP é pacote separado e não importa o examples.ts do app Next).
@@ -165,7 +165,17 @@ export async function meta(args) {
     // ponto). Sem sessão, ensina a conectar; com sessão, personaliza com
     // nome/tier/saldo e curadoria de primeiros poderes + um "comece por aqui".
     if (args.action === "start") {
-        const token = getSessionToken();
+        // start é a porta de entrada e NÃO exige login (esse é o ponto). Mas
+        // getSessionToken() LANÇA quando não há sessão (nunca retorna vazio), então
+        // sem este try/catch o primeiro contato — justo o cenário que o start existe
+        // pra resolver — estourava isError em vez de devolver o onboarding curado.
+        let token = null;
+        try {
+            token = getSessionToken();
+        }
+        catch {
+            token = null;
+        }
         if (!token) {
             return {
                 connected: false,

package/dist/tools/musicator.js

@@ -73,6 +73,15 @@ export const musicatorSchema = z.object({
         .describe("Pra action=render: seed pra reprodutibilidade do synth."),
 });
 export async function musicator(args) {
+    // list_public é o Acervo público de músicas da Comunidade (sem custo, sem
+    // login): resolve ANTES de exigir sessão. Sem isto, getSessionToken() lança
+    // pra quem não está logado e mata o caminho público (mesmo bug do meta.start).
+    if (args.action === "list_public") {
+        return await convexQuery("musicator:listPublicTracks", {
+            page: args.page,
+            limit: args.limit,
+        });
+    }
     const sessionToken = getSessionToken();
     if (args.action === "create") {
         if (!args.title || !args.context) {
@@ -143,12 +152,4 @@ export async function musicator(args) {
             toForum: args.toForum,
         });
     }
-    if (args.action === "list_public") {
-        // Acervo público de músicas da Comunidade. Query pública (sem auth), igual
-        // ao resto do Acervo (Textos/Personagens).
-        return await convexQuery("musicator:listPublicTracks", {
-            page: args.page,
-            limit: args.limit,
-        });
-    }
 }

package/dist/tools/shorts.js

@@ -17,8 +17,10 @@ import { convexAction, getSessionToken } from "../convexClient.js";
  *   - app-demo: persona + tela
  *   - reflexao: atmosfera mais lenta, contemplativa
  *
- * Retorna `{ success: true, url }` ou `{ success: false, error, isBlocked? }`.
- * O url é da Veo response e tem expiração curta — caller deve baixar logo.
+ * Retorna `{ success:true, imageId, status:'rendering', url:null }` (ASSÍNCRONO):
+ * o render VEO roda fora da chamada. Acompanhe com sapiens_video action=status
+ * imageId=<id> até status='completed' (traz a url VEO, expiração curta, baixe
+ * logo) ou 'error'/'blocked'.
  */
 export const shortsSchema = z.object({
     action: z.enum(["render"]),

package/dist/tools/studios.js

@@ -148,7 +148,7 @@ const STUDIOS = {
     },
     repertorio: {
         name: "Repertório",
-        description: "Catálogo pessoal de filme/série/anime/jogo. Importa de TMDB/Trakt/AniList. Pode virar pop-articles (lente cultural).",
+        description: "Catálogo pessoal de filme/série/anime/jogo/livro/música. Importa via OMDb/IGDB/AniList/Google Books/iTunes. Pode virar pop-articles (lente cultural).",
         url: `${APP}/u/<username>/repertorio`,
         status: "stable",
         tags: ["acervo", "filme", "anime", "jogo", "pop"],

package/dist/tools/video.js

@@ -54,7 +54,7 @@ const VIDEO_MODELS = [
     "sapiens-video-omni",
 ];
 export const videoSchema = z.object({
-    action: z.enum(["create", "generate", "demos", "showcase", "shadows", "shadows-list"]),
+    action: z.enum(["create", "generate", "status", "models", "demos", "showcase", "shadows", "shadows-list"]),
     // --- action=shadows (deepshadows: extrai o mapa de profundidade de um vídeo) ---
     videoUrl: httpUrl()
         .optional()
@@ -120,8 +120,8 @@ export const videoSchema = z.object({
     imageId: z
         .string()
         .optional()
-        .describe("action=generate: generatedImages:_id de vídeo já criado no site. O row define modelo + custo. " +
-        "Use sapiens_gallery action=list pra descobrir."),
+        .describe("action=generate ou action=status: generatedImages:_id do vídeo. O create devolve o imageId; " +
+        "ou um vídeo já criado no site (o row define modelo + custo). Use sapiens_gallery action=list pra descobrir."),
     // --- comum ---
     prompt: z
         .string()
@@ -161,6 +161,33 @@ export const videoSchema = z.object({
         .describe("Frame FINAL: url pública de galeria/Acervo/personagem. Vira reference role 'end' (suporte varia por modelo)."),
 });
 export async function video(args) {
+    // models: catálogo VIVO dos modelos de vídeo (ativos + preço-piso/config +
+    // override admin + disponibilidade). Público, sem custo e sem login — antes de
+    // exigir sessão. Espelha sapiens_image action=models.
+    if (args.action === "models") {
+        const all = await convexQuery("videoModels:listWithOverrides", {});
+        const models = (all ?? [])
+            .filter((m) => m?.isActive)
+            .map((m) => ({
+            id: m.id,
+            engine: m.engine,
+            label: m.label,
+            basePriceSinapses: m.basePriceSinapses,
+            modes: m.modes,
+            durationsSec: m.durationsSec,
+            resolutions: m.resolutions,
+            hasAudio: m.hasAudio,
+            available: m.available,
+            comingSoon: m.comingSoon,
+            note: m.description,
+        }));
+        return {
+            count: models.length,
+            default: "sapiens-video-seedance",
+            models,
+            note: "basePriceSinapses é o PISO (config mais barata, já com override admin); o preço real escala por duração x resolução [x áudio]. available=false = 'em breve' (depende de env, ex: Omni). O 'sapiens-cena-visual' (Hyperframes) não aparece: é render local, fora deste MCP.",
+        };
+    }
     const sessionToken = getSessionToken();
     if (args.action === "demos") {
         return await convexQuery("videoSpecs:mcpListMyDemoFilms", { sessionToken });
@@ -180,6 +207,15 @@ export async function video(args) {
             showcaseOrder: args.showcaseOrder,
         });
     }
+    if (args.action === "status") {
+        if (!args.imageId) {
+            throw new Error("action=status exige imageId (o que create/generate devolveu).");
+        }
+        return await convexQuery("mcpExtras:mcpVideoStatus", {
+            sessionToken,
+            imageId: args.imageId,
+        });
+    }
     if (args.action === "create") {
         if (!args.model) {
             throw new Error("action=create exige model (ex: sapiens-video-seedance, sapiens-video-kling, sapiens-video-wan, sapiens-video-kling-motion).");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sapiens-mcp",
-  "version": "1.29.0",
+  "version": "1.29.2",
   "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",
   "bin": {