@crievo/omni 0.0.0-stage → 0.1.0

package/studio/api/services/agent-ui-tools.ts

@@ -0,0 +1,259 @@
+/* Omni's UI tools: the ones that run in the browser, on the studio's screen, not here. The other half
+   of Omni's tool registry (agent-tools.ts holds the server ones: reads and staged actions). Both voice
+   modes get both halves: Grok calls them in the browser itself (lib/omni-realtime), the cascade's
+   loop sends a `ui_call` down the turn's stream and waits for the browser's result
+   (services/agent-cascade.ts, lib/omni-ui.ts).
+
+   navigate (a screen, a video's stage and the stage's tab) and open_claude only move or show things on screen: they never change data, so they need
+   no Confirmar. stop_claude, write_to_claude and send_to_claude drive a Claude session's own panel the
+   way the user's hands would (the Parar button, the message box, the send arrow), in plain sight: the
+   message sits in the box before it goes, and the descriptions tell the model to stop or send only
+   when the user asks in so many words. They are the user's direct line to a session; a request the
+   user wants checked first still goes as a card (request_change, request_reference_change).
+
+   control_editor plays and pauses the editor's player; add_epidemic_sound fills the editor's "Adicionar
+   som" box and presses its button (an Epidemic page goes to the editor's Claude, which captures the
+   track in Chrome); show_card puts a typed card in Omni's own panel (web/components/Omni/OmniCards);
+   omnichat_comments drives the "Sem DM" panel of a content's Omnichat screen (Buscar, the checks, the
+   mode and text), never its send: sending goes as a card (send_omnichat in agent-tools.ts). */
+
+import {
+  CARD_KINDS,
+  CLAUDE_TYPES,
+  isEpidemicUrl,
+  SCHEDULE_VIEWS,
+  SCREENS,
+  SETTINGS_TABS,
+  STAGE_TABS,
+  VIDEO_STAGES,
+} from "../../shared/omni-screens";
+import { referenceDir } from "./references";
+import { WAIT_TOOL_DEF, WAIT_TOOL_NAME } from "./agent-wait";
+import { videoDirs } from "./videos";
+
+/* which Claude: the same arguments for the four session tools */
+const CLAUDE_PROPS = {
+  type: { type: "string", enum: Object.keys(CLAUDE_TYPES), description: "De quem é o Claude." },
+  slug: { type: "string", description: "O slug do vídeo (de list_videos), para video e edit." },
+  name: { type: "string", description: "O nome do estilo visual (de list_references), para reference." },
+};
+
+const list = (r: Record<string, string>) =>
+  Object.entries(r)
+    .map(([k, v]) => `${k} (${v})`)
+    .join(", ");
+
+export const UI_TOOL_DEFS = [
+  {
+    type: "function" as const,
+    name: "navigate",
+    description: `Abre uma tela do studio para o usuário, e a aba dela. Use quando ele pedir para ver, abrir, mostrar ou ir para algo ("abre o vídeo do agente", "me mostra a fila", "vai pro roteiro de motion", "abre as thumbs", "abre o omnichat desse vídeo"). É a forma de mostrar: a tela do studio mostra melhor que um card. Depois diga numa frase curta o que abriu. Telas: ${list(
+      Object.fromEntries(Object.entries(SCREENS).map(([k, v]) => [k, v.label])),
+    )}.`,
+    parameters: {
+      type: "object",
+      properties: {
+        screen: { type: "string", enum: Object.keys(SCREENS), description: "A tela." },
+        slug: {
+          type: "string",
+          description: "O slug do vídeo (de list_videos), para video, video_metrics e omnichat_rule.",
+        },
+        content: {
+          type: "string",
+          enum: ["video", "carousel"],
+          description:
+            "Em omnichat_rule: o Omnichat do Reel (video, padrão) ou do carrossel. O Omnichat de um conteúdo se configura sempre nessa tela.",
+        },
+        stage: {
+          type: "string",
+          enum: Object.keys(VIDEO_STAGES),
+          description: `A etapa do vídeo a abrir: ${list(VIDEO_STAGES)}.`,
+        },
+        name: { type: "string", description: "O nome do estilo, para style." },
+        tab: {
+          type: "string",
+          enum: [...new Set([...Object.keys(SETTINGS_TABS), ...Object.values(STAGE_TABS).flatMap(Object.keys)])],
+          description: `A aba. Nas configurações: ${list(SETTINGS_TABS)}. Num vídeo, junto com stage: ${Object.entries(
+            STAGE_TABS,
+          )
+            .map(([stage, tabs]) => `em ${stage}, ${list(tabs)}`)
+            .join("; ")}.`,
+        },
+        view: { type: "string", enum: Object.keys(SCHEDULE_VIEWS), description: "A visão da agenda." },
+      },
+      required: ["screen"],
+    },
+  },
+  {
+    type: "function" as const,
+    name: "open_claude",
+    description: `Abre na tela o processo do Claude de um vídeo, do editor ou de um estilo visual: navega até lá e abre a barra lateral Processo (vídeo) ou o painel do agente (editor, estilo visual). Use quando o usuário pedir para ver o Claude, o processo, o que o agente está fazendo, ou antes de parar ou escrever para ele. Devolve o estado (running, stopped, error, interrupted ou none) e o que ele está fazendo agora. Tipos: ${list(CLAUDE_TYPES)}.`,
+    parameters: {
+      type: "object",
+      properties: CLAUDE_PROPS,
+      required: ["type"],
+    },
+  },
+  {
+    type: "function" as const,
+    name: "stop_claude",
+    description:
+      "Para o turno do Claude que está trabalhando (o botão Parar do painel): o que ele já gravou fica. Só quando o usuário pedir para parar, em palavras claras. Abre o painel se precisar. Depois a caixa de mensagem volta e dá para escrever para ele.",
+    parameters: { type: "object", properties: CLAUDE_PROPS, required: ["type"] },
+  },
+  {
+    type: "function" as const,
+    name: "write_to_claude",
+    description:
+      "Escreve uma mensagem na caixa de mensagem do Claude (abre o painel se precisar), à vista do usuário, SEM enviar. Escreva o que o usuário ditou, no tom de um pedido ao agente. Com o Claude trabalhando a caixa não existe: pare antes (stop_claude) se o usuário pediu, ou use request_change / request_reference_change, que entram na fila. Depois pergunte se pode enviar, ou envie se ele já pediu para enviar.",
+    parameters: {
+      type: "object",
+      properties: {
+        ...CLAUDE_PROPS,
+        text: { type: "string", description: "A mensagem, em português." },
+        append: { type: "boolean", description: "true acrescenta ao que já está na caixa; sem ele, substitui." },
+      },
+      required: ["type", "text"],
+    },
+  },
+  {
+    type: "function" as const,
+    name: "send_to_claude",
+    description:
+      "Envia o que está na caixa de mensagem do Claude (a seta do painel), como o usuário faria: o Claude retoma a sessão com essa mensagem. Só quando o usuário pedir para enviar ou confirmar o texto escrito. O usuário pode ter mexido no texto: vai o que está na caixa.",
+    parameters: { type: "object", properties: CLAUDE_PROPS, required: ["type"] },
+  },
+  {
+    type: "function" as const,
+    name: "control_editor",
+    description:
+      "O player do editor de um vídeo já montado (etapa Editor): play (do ponto atual, ou do segundo at), pause. Abre o editor se precisar. Use quando o usuário pedir para tocar, dar play, ouvir ou ver o vídeo no editor, ou pausar.",
+    parameters: {
+      type: "object",
+      properties: {
+        slug: { type: "string", description: "O slug do vídeo." },
+        action: { type: "string", enum: ["play", "pause"], description: "Tocar ou pausar." },
+        at: {
+          type: "number",
+          description: "Em play, o segundo de onde tocar (do vídeo editado). Sem ele, de onde parou.",
+        },
+      },
+      required: ["slug", "action"],
+    },
+  },
+  {
+    type: "function" as const,
+    name: "add_epidemic_sound",
+    description:
+      "Adiciona ao vídeo uma música ou um efeito da Epidemic Sound pelo editor: abre o editor, a aba Sons, escreve o link na caixa 'Adicionar som' e aperta o botão. Com query, pesquisa na Epidemic (escreva a busca em inglês, que é como a Epidemic indexa: 'calm piano', 'chill lofi', 'soft ambient'); com url, usa esse link. Uma página (busca, playlist) vai para o Claude do editor, que abre no Chrome, ouve e baixa a primeira faixa que o vídeo ainda não tem (leva um ou dois minutos); um MP3 do player baixa na hora. A faixa entra na biblioteca de sons do vídeo; para virar a música de fundo, o usuário arrasta para a trilha de fundo ou pede ao editor (request_change where edit). Só quando o usuário pedir.",
+    parameters: {
+      type: "object",
+      properties: {
+        slug: { type: "string", description: "O slug do vídeo." },
+        query: { type: "string", description: "A busca, em inglês (ex.: calm piano)." },
+        url: { type: "string", description: "Um link da Epidemic (página ou MP3 do player), em vez de query." },
+        kind: { type: "string", enum: ["music", "sfx"], description: "Música (padrão) ou efeito." },
+        name: { type: "string", description: "Nome curto do arquivo, em minúsculas com hífens (ex.: musica-calma)." },
+      },
+      required: ["slug"],
+    },
+  },
+  {
+    type: "function" as const,
+    name: "show_card",
+    description: `Mostra um card no painel da Omni, sem sair da tela: ${list(CARD_KINDS)}. Só quando o usuário pedir para ver aqui no painel, sem sair da tela onde está. Para mostrar algo, o padrão é abrir a tela dele com navigate (thumbnails: stage publish, tab thumbnail; o vídeo exportado: stage publish; o carrossel: stage carousel-publish; uma cena: stage motion; os números: video_metrics; o Omnichat: omnichat_rule). Depois diga numa frase o que mostrou.`,
+    parameters: {
+      type: "object",
+      properties: {
+        kind: { type: "string", enum: Object.keys(CARD_KINDS), description: "O card." },
+        slug: { type: "string", description: "O slug do conteúdo (todos menos reference)." },
+        name: { type: "string", description: "O nome do estilo visual (reference)." },
+        scene: { type: "string", description: "A cena (ex.: c03), em scene." },
+      },
+      required: ["kind"],
+    },
+  },
+  {
+    type: "function" as const,
+    name: "ask_in_chat",
+    description:
+      "Abre o chat do painel da Omni com o campo de texto focado, para o usuário colar um link ou escrever um texto que você precisa e que não dá para ditar por voz. Use quando o pedido depende de um link (um vídeo para virar referência, uma página, um Epidemic) ou de um texto longo (um roteiro, uma mensagem). Chame e diga numa frase o que colar. Se ele responder por voz (um não, outro caminho), o chat fecha sozinho; se escrever, o chat fica.",
+    parameters: {
+      type: "object",
+      properties: {
+        what: { type: "string", enum: ["link", "text"], description: "O que você precisa: um link ou um texto." },
+      },
+    },
+  },
+  {
+    type: "function" as const,
+    name: "omnichat_comments",
+    description:
+      "O painel Sem DM da tela do Omnichat de um conteúdo publicado (abre a tela /omnichat/video/<slug> se precisar), à vista do usuário. action fetch: busca no post agora quem comentou e não recebeu a DM (o que a regra pulou, ainda não pegou, não dispara ou falhou) e devolve a lista com o id de cada comentário, se pede o link (asks) e se ainda dá para mandar a DM (can_get_dm: até 7 dias). action select: marca na tela os comentários escolhidos (ids, ou all_asking: true para todos que pedem) e o modo (both, dm ou comment) com o texto da resposta, sem mandar nada. Para mandar, depois chame send_omnichat (um card que só vai com o sim do usuário). Use quando ele pedir para ver os comentários sem resposta, quem ficou sem DM, ou para mandar a DM a quem pediu.",
+    parameters: {
+      type: "object",
+      properties: {
+        slug: { type: "string", description: "O slug do conteúdo." },
+        content: { type: "string", enum: ["video", "carousel"], description: "O Reel (video, padrão) ou o carrossel." },
+        action: { type: "string", enum: ["fetch", "select"], description: "Buscar a lista ou marcar na tela." },
+        ids: { type: "array", items: { type: "string" }, description: "Em select: os ids dos comentários." },
+        all_asking: { type: "boolean", description: "Em select: todos que pedem e ainda podem receber." },
+        mode: {
+          type: "string",
+          enum: ["both", "dm", "comment"],
+          description: "Em select: DM e resposta (both), só a DM (dm) ou só a resposta no comentário (comment).",
+        },
+        text: { type: "string", description: "Em select: a resposta no comentário (obrigatória em comment)." },
+      },
+      required: ["slug", "action"],
+    },
+  },
+  /* the call sleeps while a studio Claude works (agent-wait.ts; the browser owns mic and socket) */
+  WAIT_TOOL_DEF,
+];
+
+const NAMES = new Set(UI_TOOL_DEFS.map(t => t.name));
+export const isUiTool = (name: string) => NAMES.has(name);
+
+/* what the server can check before the browser runs the call: a video or reference that exists
+   (null: fine) */
+export function checkUiCall(name: string, rawArgs: string): string | null {
+  if (!isUiTool(name)) return null;
+  let a: {
+    screen?: string;
+    type?: string;
+    kind?: string;
+    slug?: string;
+    name?: string;
+    text?: string;
+    scene?: string;
+    query?: string;
+    url?: string;
+  };
+  try {
+    a = JSON.parse(rawArgs || "{}");
+  } catch {
+    return "argumentos não são JSON";
+  }
+  const video =
+    name === "navigate"
+      ? a.screen === "video" || a.screen === "video_metrics" || a.screen === "omnichat_rule"
+      : name === "show_card"
+        ? a.kind !== "reference"
+        : name === "omnichat_comments" || a.type !== "reference";
+  if (video && a.slug && !videoDirs().has(a.slug))
+    return `vídeo não encontrado: ${a.slug}. Use list_videos para achar o slug.`;
+  /* wait_for_work may name no Claude at all (any that is working) */
+  if (video && name !== "navigate" && name !== WAIT_TOOL_NAME && !a.slug)
+    return "falta o slug do vídeo (use list_videos)";
+  if ((a.type === "reference" || a.kind === "reference") && (!a.name || !referenceDir(a.name)))
+    return `estilo visual não encontrado: ${a.name ?? ""}. Use list_references para achar o nome.`;
+  if (name === "add_epidemic_sound") {
+    if (!a.query?.trim() && !a.url?.trim()) return "diga a busca (query) ou o link (url)";
+    if (a.url && !isEpidemicUrl(a.url)) return "o link precisa ser da Epidemic Sound (epidemicsound.com)";
+    if (a.name && !/^[a-z0-9][a-z0-9-]{0,60}$/.test(a.name)) return "nome: minúsculas, números e hífens";
+  }
+  if (name === "show_card" && a.kind === "scene" && !/^c\d{1,3}$/.test(a.scene ?? "")) return "diga a cena (ex.: c03)";
+  if (name === "write_to_claude" && !String(a.text ?? "").trim()) return "escreva a mensagem em text";
+  return null;
+}

package/studio/api/services/agent-wait.ts

@@ -0,0 +1,32 @@
+/* Omni's wait: after a request that leaves a studio Claude working for minutes, the call goes to
+   sleep instead of hanging up or talking over the silence. Grok's socket closes (it bills every open
+   second), the cascade stops streaming to the STT, and the page keeps only the microphone with a local,
+   free voice detector. It wakes when the user speaks or when the awaited Claude stops, and tells the
+   result (web/lib/omni-wait.ts and the two conversation classes). Past `agent.wait_max_min` asleep,
+   it hangs up for good.
+
+   `wait_for_work` is a UI tool: it runs in the browser, which owns the microphone and the socket. It
+   belongs in agent-ui-tools.ts UI_TOOL_DEFS, so Grok gets it in the session and the cascade routes it
+   down the turn's stream as a `ui_call`. */
+
+export const WAIT_TOOL_NAME = "wait_for_work";
+
+export const WAIT_TOOL_DEF = {
+  type: "function" as const,
+  name: WAIT_TOOL_NAME,
+  description:
+    "Põe a conversa para esperar o trabalho do estúdio sem gastar: a voz desliga, o microfone fica aberto e você volta sozinha quando o usuário falar ou quando o Claude que está trabalhando terminar, para contar o resultado. Chame depois de um Confirmar que deixou o Claude trabalhando (alteração, conteúdo novo, thumbnails, pedido num estilo visual, resposta de aprovação), ou quando o usuário disser que vai esperar ou pedir para avisar quando terminar. Antes, diga numa frase curta que vai esperar e que é só falar para chamar você. Com type e slug (ou name, num estilo visual), espera aquele Claude; sem eles, qualquer Claude que estiver trabalhando.",
+  parameters: {
+    type: "object",
+    properties: {
+      type: {
+        type: "string",
+        enum: ["video", "edit", "reference"],
+        description: "De quem é o Claude a esperar: o do vídeo, o do editor ou o de um estilo visual.",
+      },
+      slug: { type: "string", description: "O slug do vídeo, para video e edit." },
+      name: { type: "string", description: "O nome do estilo visual, para reference." },
+    },
+    required: [],
+  },
+};