@crievo/omni 0.0.0-stage → 0.1.1

package/studio/shared/omni-admin.ts

@@ -0,0 +1,52 @@
+/* What the admin panel (/admin) offers for Omni, the same for every user: the engine Omni runs on,
+   the cascade's language model (OpenRouter), its voice and its voice model. The server checks a
+   choice against these lists (services/admin.ts) and the page draws its selects from them. */
+
+export type OmniEngine = "grok" | "stream" | "chunks";
+
+export const OMNI_ENGINES: { id: OmniEngine; label: string; hint: string }[] = [
+  { id: "grok", label: "Grok Voice", hint: "xAI de voz para voz; cobra cada minuto aberto (US$ 0,08/min)" },
+  {
+    id: "stream",
+    label: "Cascata em streaming",
+    hint: "STT da xAI em streaming → modelo do OpenRouter → Fish (US$ 0,20/h de microfone aberto)",
+  },
+  {
+    id: "chunks",
+    label: "Cascata por trechos",
+    hint: "cada fala vai inteira ao STT → modelo do OpenRouter → Fish (só a fala é cobrada)",
+  },
+];
+
+/* the cascade's language model, by its OpenRouter id */
+export const OMNI_LLMS: { id: string; label: string }[] = [
+  { id: "anthropic/claude-haiku-5.5", label: "Claude Haiku 5.5" },
+  { id: "openai/gpt-6-luna", label: "GPT-6 Luna" },
+  { id: "google/gemini-3.8-flash", label: "Gemini 3.8 Flash" },
+];
+
+/* Grok's voices (agent.voices): picking one sets agent.gender */
+export const GROK_VOICES: { id: string; label: string; gender: "female" | "male" }[] = [
+  { id: "ara", label: "Ara (feminina)", gender: "female" },
+  { id: "rex", label: "Rex (masculina)", gender: "male" },
+];
+
+/* the cascade's Fish voices (agent.cascade.voice), from Fish's library and the account */
+export const FISH_VOICES: { id: string; label: string; gender: "female" | "male" }[] = [
+  { id: "6ccc1431468e4ef69fca0054fe5898cd", label: "Omni", gender: "female" },
+  { id: "148da69cf74b4530b1c41d5c1e87c688", label: "Mulher comum", gender: "female" },
+  { id: "c7d997eba056434d8ba3dd1b8dec560e", label: "Linn", gender: "male" },
+];
+
+/* the cascade's voice model (agent.cascade.fish_model) */
+export const FISH_MODELS: { id: string; label: string }[] = [
+  { id: "s2.1-pro-free", label: "Fish S2.1 Pro grátis" },
+  { id: "s2.1-pro", label: "Fish S2.1 Pro (pago)" },
+];
+
+/* the engine a config holds: agent.engine, or, from before it, agent.grok false = the cascade */
+export function engineOf(agent: { engine?: unknown; grok?: unknown } | undefined): OmniEngine {
+  const e = agent?.engine;
+  if (e === "grok" || e === "stream" || e === "chunks") return e;
+  return agent?.grok === false ? "stream" : "grok";
+}

package/studio/shared/omni-farewell.ts

@@ -0,0 +1,48 @@
+/* The user saying goodbye to Omni ("tchau", "pode terminar", "valeu, até logo"): the call ends with
+   "Até logo!" without waiting for the model to decide it. Only an utterance that is nothing but the
+   goodbye counts: "tchau, mas antes abre o vídeo" goes to the model like any other. The cascade
+   checks it on the server (agent-cascade.ts), Grok's page on the user's transcript (omni-realtime). */
+
+/* the goodbye itself, in normalized text (lowercase, no accents or punctuation) */
+const FAREWELLS = [
+  /\b(?:tchau|tchauzinho|xau|xauzinho|chau)\b/,
+  /\bate (?:logo|mais|a proxima|amanha|depois|breve|outra hora)\b/,
+  /\b(?:falou|flw|fui)\b/,
+  /\b(?:pode|vamos|vou|quero) (?:terminar|encerrar|desligar|fechar|finalizar|parar por aqui)\b/,
+  /\b(?:encerra|encerrar|desliga|desligar|termina|terminar|finaliza|finalizar)\b/,
+  /\b(?:por hoje e so|era so isso|e so isso por hoje|nao preciso de mais nada)\b/,
+];
+/* what may come with it: thanks, "ok", "a conversa", "por aqui", "boa noite"… */
+const AROUND = new Set(
+  (
+    "ok okay entao beleza blz valeu vlw obrigado obrigada brigado brigada muito mesmo omni bom boa ta otimo " +
+    "perfeito show e a o conversa ligacao chamada papo por aqui hoje ai agora ja pode isso noite tarde dia " +
+    "beijo beijos abraco abracos gata querida linda tudo certo"
+  ).split(" "),
+);
+
+export const normalizeSpeech = (text: string) =>
+  text
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/[̀-ͯ]/g, "")
+    .replace(/[^a-z0-9\s]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+
+export function isFarewell(text: string): boolean {
+  let t = normalizeSpeech(text);
+  if (!t || t.split(" ").length > 12) return false;
+  let found = false;
+  for (const re of FAREWELLS) {
+    const g = new RegExp(re.source, "g");
+    if (g.test(t)) {
+      found = true;
+      t = t.replace(g, " ");
+    }
+  }
+  return found && t.split(" ").every(w => !w || AROUND.has(w));
+}
+
+/* what Omni says before hanging up */
+export const FAREWELL_REPLY = "Até logo!";

package/studio/shared/omni-hotword.ts

@@ -0,0 +1,20 @@
+/* "Oi, Omni": the words that call Omni with its panel closed (lib/omni-hotword.ts listens, the server's
+   /api/agent/hotword transcribes the start of each utterance and checks it here). Only the start counts:
+   the name in its first words, after at most a greeting ("oi", "ei", "olha"…). "Omnichat" or "o homem"
+   don't call it. The STT writes the name in a few ways (measured 2026-10-17: "Omni", "Ômini",
+   "homini"); "homem" stays out, "ei, homem" is a real sentence. */
+
+import { normalizeSpeech } from "./omni-farewell";
+
+const NAME = new Set(["omni", "omini", "homini", "hominy", "ominy", "omne", "ommi"]);
+/* what may come before the name */
+const BEFORE = new Set(["oi", "ei", "ey", "hey", "e", "ai", "ah", "eh", "olha", "ola", "alo", "o", "ow", "opa"]);
+
+export function isHotword(text: string): boolean {
+  const words = normalizeSpeech(text).split(" ").slice(0, 4);
+  for (const w of words) {
+    if (NAME.has(w)) return true;
+    if (!BEFORE.has(w)) return false;
+  }
+  return false;
+}

package/studio/shared/omni-screens.ts

@@ -0,0 +1,228 @@
+/* The studio screens Omni can open (the `navigate` UI tool) and how a path reads back as "where the
+   user is" (the screen context of each turn). One catalog for the server, which hands it to the LLM,
+   and for the browser, which builds the route and navigates (web/lib/omni-ui.ts). Paths follow
+   web/router.tsx. */
+
+export type ScreenId =
+  | "home"
+  | "videos"
+  | "video"
+  | "analytics"
+  | "video_metrics"
+  | "new"
+  | "styles"
+  | "style"
+  | "voice"
+  | "queue"
+  | "schedule"
+  | "omnichat"
+  | "omnichat_rule"
+  | "settings"
+  | "usage"
+  | "omni_measures"
+  | "getting_started";
+
+/* label: how Omni names the screen to the user (and how it reads in the screen context) */
+export const SCREENS: Record<ScreenId, { label: string; path: string }> = {
+  home: { label: "Início", path: "/" },
+  videos: { label: "Conteúdos", path: "/videos" },
+  video: { label: "Vídeo", path: "/videos/$slug" },
+  analytics: { label: "Análise do canal", path: "/analytics" },
+  video_metrics: { label: "Métricas de um Reel", path: "/analytics/$slug" },
+  new: { label: "Novo conteúdo", path: "/new" },
+  styles: { label: "Estilos visuais", path: "/styles" },
+  style: { label: "Um estilo visual", path: "/styles/$name" },
+  voice: { label: "Voz", path: "/voice" },
+  queue: { label: "Fila da máquina", path: "/queue" },
+  schedule: { label: "Agenda de publicação", path: "/schedule" },
+  omnichat: { label: "Omnichat", path: "/omnichat" },
+  /* where a content's Omnichat is set up, always: /omnichat/video/<slug> (or carousel) */
+  omnichat_rule: { label: "Omnichat de um conteúdo", path: "/omnichat/$kind/$id" },
+  settings: { label: "Configurações", path: "/settings" },
+  usage: { label: "Uso das vozes", path: "/usage" },
+  omni_measures: { label: "Medições do Omni", path: "/agent" },
+  getting_started: { label: "Primeiros passos", path: "/getting-started" },
+};
+
+/* the stages of a video (web/lib/stages.ts), as the video screen's tabs */
+export const VIDEO_STAGES: Record<string, string> = {
+  script: "Roteiro do conteúdo",
+  motion_script: "Roteiro de motion",
+  motion: "Composição",
+  narration: "Narração, voz e tempo",
+  voice: "Voz (escolha das falas)",
+  render: "Editor (timeline, legenda e exportação)",
+  captions: "Legenda (aba do editor)",
+  export: "Exportação (no editor)",
+  publish: "Publicar",
+  "carousel-script": "Roteiro do carrossel",
+  "carousel-composition": "Composição do carrossel",
+  "carousel-publish": "Publicar o carrossel",
+};
+
+/* the tabs inside a video stage (navigate with stage and tab): the publication's, the carousel's and the
+   editor's. The stage registers a handle that switches them (web/lib/omni-ui.ts, stageTabsKey) */
+export const STAGE_TABS: Record<string, Record<string, string>> = {
+  publish: { info: "Informações do vídeo (publicar e agendar)", thumbnail: "Thumbnail" },
+  "carousel-publish": { post: "Post (publicar o carrossel)" },
+  render: {
+    agent: "Agente (o chat do editor)",
+    settings: "Ajustes",
+    sounds: "Sons",
+    captions: "Legenda",
+    cuts: "Cortes",
+    scenes: "Cenas",
+  },
+};
+/* the "Sem DM" panel of a content's Omnichat screen (the omnichat_comments UI tool drives it) */
+export const missingDmsKey = (content: "video" | "carousel", slug: string) => `missing-dms:${content}:${slug}`;
+export const stageTabsKey = (slug: string, stage: string) =>
+  stage === "render" ? `editor:${slug}` : `stage-tabs:${slug}:${stage}`;
+
+export const SETTINGS_TABS: Record<string, string> = {
+  voice: "Voz",
+  usage: "Uso",
+  agent: "Omni",
+  platforms: "Plataformas",
+  publishing: "Publicação",
+  providers: "Provedores",
+};
+
+export const SCHEDULE_VIEWS: Record<string, string> = { month: "mês", week: "semana", day: "dia" };
+
+export type NavigateArgs = {
+  screen: ScreenId;
+  slug?: string;
+  /* omnichat_rule: the Reel's rule (video, the default) or the carousel's */
+  content?: "video" | "carousel";
+  stage?: string;
+  name?: string;
+  tab?: string;
+  view?: string;
+};
+
+const SLUG = /^[\w.-]{1,120}$/;
+
+/* the route for these arguments, or why it can't be opened (in Portuguese, for the model) */
+export type Route = { to: string; params: Record<string, string>; tab?: string };
+export function routeFor(a: NavigateArgs): Route | { error: string } {
+  const screen = SCREENS[a.screen];
+  if (!screen) return { error: `tela desconhecida: ${a.screen}` };
+  if (a.screen === "video" || a.screen === "video_metrics") {
+    if (!a.slug || !SLUG.test(a.slug)) return { error: "falta o slug do vídeo (use list_videos)" };
+    if (a.screen === "video" && a.stage) {
+      if (!(a.stage in VIDEO_STAGES)) return { error: `etapa desconhecida: ${a.stage}` };
+      const route = { to: "/videos/$slug/$stage", params: { slug: a.slug, stage: a.stage } };
+      if (!a.tab) return route;
+      const tabs = STAGE_TABS[a.stage];
+      if (!tabs) return { error: `a etapa ${a.stage} não tem abas` };
+      if (!(a.tab in tabs))
+        return { error: `aba desconhecida em ${a.stage}: ${a.tab} (são ${Object.keys(tabs).join(", ")})` };
+      return { ...route, tab: a.tab };
+    }
+    if (a.tab) return { error: "aba de vídeo só com stage (publish, carousel-publish ou render)" };
+    return { to: screen.path, params: { slug: a.slug } };
+  }
+  if (a.screen === "omnichat_rule") {
+    if (!a.slug || !SLUG.test(a.slug)) return { error: "falta o slug do conteúdo (use list_videos)" };
+    return { to: screen.path, params: { kind: a.content === "carousel" ? "carousel" : "video", id: a.slug } };
+  }
+  if (a.screen === "style") {
+    if (!a.name || !SLUG.test(a.name)) return { error: "falta o nome do estilo" };
+    return { to: screen.path, params: { name: a.name } };
+  }
+  if (a.screen === "settings" && a.tab) {
+    if (!(a.tab in SETTINGS_TABS)) return { error: `aba desconhecida: ${a.tab}` };
+    return { to: "/settings/$category", params: { category: a.tab } };
+  }
+  if (a.screen === "schedule" && a.view && a.view !== "month") {
+    if (!(a.view in SCHEDULE_VIEWS)) return { error: `visão desconhecida: ${a.view}` };
+    return { to: "/schedule/$view", params: { view: a.view } };
+  }
+  return { to: screen.path, params: {} };
+}
+
+/* a path as a sentence: "Vídeo 2026-10-14-x, etapa Roteiro de motion" */
+export function describePath(path: string): string {
+  const p = path.replace(/[?#].*$/, "").replace(/\/+$/, "") || "/";
+  const parts = p.split("/").filter(Boolean).map(decodeURIComponent);
+  if (!parts.length) return SCREENS.home.label;
+  const [root, a, b] = parts;
+  if (root === "videos" && a) return `${SCREENS.video.label} ${a}${b ? `, etapa ${VIDEO_STAGES[b] ?? b}` : ""}`;
+  if (root === "analytics" && a) return `${SCREENS.video_metrics.label} (${a})`;
+  if (root === "styles" && a) return `${SCREENS.style.label}: ${a}`;
+  if (root === "omnichat" && a && b)
+    return `Omnichat ${a === "carousel" ? "do carrossel" : a === "post" ? "do post" : "do vídeo"} ${b}`;
+  if (root === "settings" && a) return `${SCREENS.settings.label}, aba ${SETTINGS_TABS[a] ?? a}`;
+  if (root === "schedule" && a) return `${SCREENS.schedule.label}, visão por ${SCHEDULE_VIEWS[a] ?? a}`;
+  const hit = Object.values(SCREENS).find(s => s.path === `/${root}`);
+  return hit?.label ?? p;
+}
+
+/* --- the Claude processes on screen ----------------------------------------------------------- */
+/* where each studio Claude session lives (the UI tools open_claude, stop_claude, write_to_claude,
+   send_to_claude): a video's in the "Processo" sidebar, the editor's chat in the Editor stage, a
+   reference's on its page. The channel analysis is left out: its panel sits inside a Reel's tabs */
+export type ClaudeType = "video" | "edit" | "reference";
+export const CLAUDE_TYPES: Record<ClaudeType, string> = {
+  video: "o Claude do vídeo (pipeline), na barra lateral Processo",
+  edit: "o chat do editor de um vídeo já montado",
+  reference: "o Claude de um estilo visual",
+};
+export type ClaudeArgs = { type: ClaudeType; slug?: string; name?: string };
+
+/* the session's target (slug or reference name) and the screen that shows it, or why not */
+export function claudeTarget(
+  a: ClaudeArgs,
+): { target: string; route: { to: string; params: Record<string, string> } } | { error: string } {
+  if (a.type === "reference") {
+    if (!a.name || !/^[a-z0-9][a-z0-9-]{0,62}$/.test(a.name))
+      return { error: "falta o nome do estilo visual (use list_references)" };
+    return { target: a.name, route: { to: SCREENS.style.path, params: { name: a.name } } };
+  }
+  if (a.type !== "video" && a.type !== "edit") return { error: `tipo desconhecido: ${a.type}` };
+  if (!a.slug || !SLUG.test(a.slug)) return { error: "falta o slug do vídeo (use list_videos)" };
+  return {
+    target: a.slug,
+    route:
+      a.type === "edit"
+        ? { to: "/videos/$slug/$stage", params: { slug: a.slug, stage: "render" } }
+        : { to: SCREENS.video.path, params: { slug: a.slug } },
+  };
+}
+
+/* already there: a video's sidebar opens over any of its stages, so its Claude needs no navigation */
+export function onClaudeScreen(a: ClaudeArgs, path: string): boolean {
+  const p = path.replace(/[?#].*$/, "").replace(/\/+$/, "");
+  const parts = p.split("/").filter(Boolean).map(decodeURIComponent);
+  if (a.type === "video") return parts[0] === "videos" && parts[1] === a.slug;
+  if (a.type === "edit") return parts[0] === "videos" && parts[1] === a.slug && parts[2] === "render";
+  return parts[0] === "styles" && parts[1] === a.name;
+}
+
+/* --- the cards Omni shows in its panel (show_card; web/components/Omni/OmniCards) ----------------- */
+export const CARD_KINDS = {
+  video: "o conteúdo: capa, título, etapa, onde foi publicado",
+  thumbnails: "as versões da thumbnail, com a escolhida",
+  export: "o player do vídeo exportado",
+  scene: "o quadro de uma cena (scene)",
+  carousel: "os slides do carrossel",
+  metrics: "os números do Reel publicado",
+  reference: "um estilo visual: quadro, título e essência (name)",
+} as const;
+export type CardKind = keyof typeof CARD_KINDS;
+
+/* --- Epidemic Sound (add_epidemic_sound) -------------------------------------------------------- */
+/* a search page on Epidemic: the editor's agent opens it in Chrome, plays the tracks and downloads the
+   first one the video doesn't have (api/services/sound.ts captureFromPage) */
+export function epidemicSearchUrl(query: string, kind: "music" | "sfx" = "music"): string {
+  const base =
+    kind === "music"
+      ? "https://www.epidemicsound.com/music/search/?term="
+      : "https://www.epidemicsound.com/sound-effects/search/?term=";
+  return `${base}${encodeURIComponent(query.trim())}`;
+}
+
+/* an Epidemic link the "Adicionar som" box takes: a page on epidemicsound.com or a player MP3 */
+export const isEpidemicUrl = (url: string) =>
+  /^https:\/\/(www\.)?epidemicsound\.com\//.test(url) || /^https:\/\/audiocdn\.epidemicsound\.com\/lqmp3\//.test(url);

package/studio/shared/schemas/admin.ts

@@ -0,0 +1,15 @@
+/* The admin panel (/admin): POST /api/admin/omni changes one or more of Omni's settings for every user.
+   The values are checked against shared/omni-admin's lists on the server. */
+
+import { z } from "zod";
+
+export const omniAdminBody = z
+  .object({
+    enabled: z.boolean(),
+    engine: z.enum(["grok", "stream", "chunks"]),
+    voice: z.string().max(64),
+    fish_model: z.string().max(64),
+    llm: z.string().max(120),
+  })
+  .partial();
+export type OmniAdminBody = z.infer<typeof omniAdminBody>;

package/studio/shared/schemas/agent-cascade.ts

@@ -0,0 +1,58 @@
+/* Omni in cascade mode (speech → text → a fast LLM with the tools → Fish voice): the session, each
+   turn and what the browser measures. */
+
+import { z } from "zod";
+
+/* "stream": the microphone streams to xAI's STT WebSocket; "chunks": each utterance is posted whole */
+export const cascadeMode = z.enum(["stream", "chunks"]);
+export type CascadeMode = z.infer<typeof cascadeMode>;
+
+/* POST /api/agent/cascade/session; `history`: the lines of an earlier conversation the user continues */
+export const cascadeSessionBody = z.object({
+  mode: cascadeMode,
+  history: z
+    .array(z.object({ role: z.enum(["user", "assistant"]), text: z.string().min(1).max(4000) }))
+    .max(80)
+    .optional(),
+});
+export type CascadeSessionBody = z.infer<typeof cascadeSessionBody>;
+
+/* POST /api/agent/cascade/:id/turn: what the user said (or typed, or "[Tela] …" after a Confirmar);
+   speculative: started on the STT's locked text before the end of the turn, confirmed by /commit */
+export const cascadeTurnBody = z.object({
+  text: z.string().min(1).max(4000),
+  speculative: z.boolean().optional(),
+  /* the path on screen, for "esse vídeo" (shared/omni-screens.ts reads it) */
+  screen: z.string().max(300).optional(),
+});
+export type CascadeTurnBody = z.infer<typeof cascadeTurnBody>;
+
+/* POST /api/agent/cascade/:id/ui-result: what a UI tool did in the browser */
+export const cascadeUiResultBody = z.object({
+  call_id: z.string().max(200),
+  output: z.record(z.string(), z.unknown()),
+});
+export type CascadeUiResultBody = z.infer<typeof cascadeUiResultBody>;
+
+/* POST /api/agent/cascade/:id/log: the browser's side of a turn and of the session */
+export const cascadeLogBody = z.discriminatedUnion("type", [
+  /* end of the user's speech → first audio played, and how long the text took to arrive */
+  z.object({
+    type: z.literal("turn"),
+    latency_ms: z.number(),
+    stt_ms: z.number().nullable(),
+    llm_first_ms: z.number().nullable(),
+    tts_first_ms: z.number().nullable(),
+    item: z.string().optional(),
+  }),
+  z.object({ type: z.literal("feedback"), item: z.string(), value: z.enum(["up", "down", "none"]) }),
+  /* stt_audio_s: seconds of audio streamed to the STT (stream mode bills them) */
+  z.object({
+    type: z.literal("end"),
+    duration_s: z.number(),
+    stt_audio_s: z.number().optional(),
+    reason: z.string().optional(),
+  }),
+  z.object({ type: z.literal("error"), message: z.string() }),
+]);
+export type CascadeLogBody = z.infer<typeof cascadeLogBody>;

package/studio/shared/schemas/agent-history.ts

@@ -0,0 +1,73 @@
+/* Omni's conversation history (api/services/agent-history.ts): what the browser saves of a call and
+   what the Conversas list reads back. */
+
+import { z } from "zod";
+
+export const CONVERSATION_ID = /^[\w-]{1,80}$/;
+
+const text = (max: number) => z.string().max(max);
+
+/* one line of the transcript, the shape of web/lib/omni-realtime.ts OmniEntry */
+export const conversationEntry = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("user"), id: text(120), text: text(8000), pending: z.boolean().optional() }),
+  z.object({
+    kind: z.literal("assistant"),
+    id: text(120),
+    text: text(8000),
+    latency_ms: z.number().nullable().optional(),
+    feedback: z.enum(["up", "down"]).nullable().optional(),
+    breakdown: text(300).optional(),
+  }),
+  z.object({
+    kind: z.literal("tool"),
+    id: text(200),
+    name: text(80),
+    state: z.enum(["running", "ok", "error"]),
+    detail: text(2000).nullable().optional(),
+    ms: z.number().nullable().optional(),
+  }),
+  z.object({ kind: z.literal("note"), id: text(120), text: text(2000) }),
+]);
+export type ConversationEntry = z.infer<typeof conversationEntry>;
+
+/* a card Omni staged, and what became of it */
+export const conversationAction = z.object({
+  id: text(40),
+  kind: text(40),
+  slug: text(120).nullable().optional(),
+  summary: text(2000),
+  state: z.enum(["staged", "confirmed", "failed", "canceled"]),
+  at: text(40),
+});
+export type ConversationAction = z.infer<typeof conversationAction>;
+
+/* POST /api/agent/conversations/:id: the whole conversation so far (each save replaces the last) */
+export const conversationSaveBody = z.object({
+  mode: z.enum(["grok", "stream", "chunks"]),
+  /* the voice sessions it used (a continued conversation adds one each time) */
+  sessions: z.array(text(100)).max(50),
+  entries: z.array(conversationEntry).max(600),
+  actions: z.array(conversationAction).max(100),
+  started_at: text(40),
+});
+export type ConversationSaveBody = z.infer<typeof conversationSaveBody>;
+
+/* GET /api/agent/conversations/:id: what is kept, with the title (the first request) and when */
+export type Conversation = ConversationSaveBody & {
+  id: string;
+  title: string;
+  created_at: string;
+  updated_at: string;
+};
+/* GET /api/agent/conversations: the list, newest first */
+export type ConversationSummary = {
+  id: string;
+  title: string;
+  mode: Conversation["mode"];
+  created_at: string;
+  updated_at: string;
+  /* what the user said, and the cards it staged and confirmed */
+  messages: number;
+  actions: number;
+  confirmed: number;
+};

package/studio/shared/schemas/agent.ts

@@ -0,0 +1,50 @@
+/* Omni, the voice agent (AgentPage): voice choice, the tool calls the browser forwards from Grok,
+   the confirmation of a staged publish and the measurement log. */
+
+import { z } from "zod";
+
+/* POST /api/agent/voice: Omni speaks with the female or the male voice */
+export const agentVoiceBody = z.object({ gender: z.enum(["female", "male"]) });
+export type AgentVoiceBody = z.infer<typeof agentVoiceBody>;
+
+/* POST /api/agent/avatar: Omni's face, a seed like a voice's avatar (`h<hue>-<suffix>`) */
+export const AVATAR_SEED = /^[\w-]{1,40}$/;
+export const agentAvatarBody = z.object({ avatar: z.string().regex(AVATAR_SEED) });
+export type AgentAvatarBody = z.infer<typeof agentAvatarBody>;
+
+/* POST /api/agent/session: a new Grok session, or `resume` (its id) to wake a call that slept waiting
+   for the studio's work */
+export const agentSessionBody = z.object({ resume: z.string().max(100).optional() });
+export type AgentSessionBody = z.infer<typeof agentSessionBody>;
+
+/* POST /api/agent/tools: one function call from Grok, as it arrived (arguments is a JSON string) */
+export const agentToolBody = z.object({
+  session: z.string(),
+  call_id: z.string(),
+  name: z.string(),
+  arguments: z.string(),
+  /* how many times the user spoke so far in this call (the page counts): confirm_action needs the
+     user to have spoken after the card appeared */
+  heard: z.number().int().min(0).optional(),
+});
+export type AgentToolBody = z.infer<typeof agentToolBody>;
+
+/* POST /api/agent/sessions/:id/log: what the browser measures */
+export const agentLogBody = z.discriminatedUnion("type", [
+  /* end of the user's speech → first audio of the reply */
+  z.object({ type: z.literal("turn"), latency_ms: z.number(), item: z.string().optional() }),
+  z.object({ type: z.literal("feedback"), item: z.string(), value: z.enum(["up", "down", "none"]) }),
+  /* reason "wait": the call only went to sleep (wait_for_work); its cards stay */
+  z.object({ type: z.literal("end"), duration_s: z.number(), reason: z.string().optional() }),
+  z.object({ type: z.literal("error"), message: z.string() }),
+]);
+export type AgentLogBody = z.infer<typeof agentLogBody>;
+
+/* POST /api/agent/stt: Claude mode, the page's recording as PCM16 mono 24 kHz in base64 (≤ 2 min) */
+export const agentSttBody = z.object({ session: z.string().max(100), audio: z.string().max(8_000_000) });
+export type AgentSttBody = z.infer<typeof agentSttBody>;
+
+/* POST /api/agent/hotword: the start of an utterance heard with the panel closed (lib/omni-hotword.ts),
+   PCM16 mono 24 kHz in base64 (≤ ~3 s) */
+export const agentHotwordBody = z.object({ audio: z.string().max(400_000) });
+export type AgentHotwordBody = z.infer<typeof agentHotwordBody>;

package/studio/shared/schemas/analytics.ts

@@ -0,0 +1,6 @@
+/* Analytics (AnalyticsPage): Claude's analysis of the channel or of one Reel. */
+
+import { z } from "zod";
+
+export const analyzeBody = z.object({ slug: z.string().optional(), focus: z.string().optional() });
+export type AnalyzeBody = z.infer<typeof analyzeBody>;

package/studio/shared/schemas/approval.ts

@@ -0,0 +1,22 @@
+/* Script and scene approval (ScriptApprovalPanel, ScenesApprovalPanel). */
+
+import { z } from "zod";
+
+/* POST …/scenes/decide */
+export const sceneDecisionBody = z.object({
+  scene: z.string(),
+  decision: z.enum(["approve", "change"]),
+  comment: z.string().optional(),
+});
+export type SceneDecisionBody = z.infer<typeof sceneDecisionBody>;
+
+/* POST …/script/decide */
+export const scriptDecisionBody = z.object({
+  decision: z.enum(["approve", "change"]),
+  comment: z.string().optional(),
+});
+export type ScriptDecisionBody = z.infer<typeof scriptDecisionBody>;
+
+/* POST …/script/edit: the script text written on the UI (which approves it) */
+export const scriptEditBody = z.object({ text: z.string() });
+export type ScriptEditBody = z.infer<typeof scriptEditBody>;

package/studio/shared/schemas/captions.ts

@@ -0,0 +1,19 @@
+/* Captions (CaptionPositionEditor): the frame query, position and text edits. */
+
+import { z } from "zod";
+
+/* GET /api/videos/:slug/captions/frame?t=<seconds> */
+export const frameQuery = z.object({ t: z.string().optional() });
+
+/* POST …/captions/position: one scope at a time; `value` is checked field by field by the service
+   (null clears a scene's or caption's own position) */
+export const captionPositionBody = z.object({
+  scope: z.enum(["video", "scene", "caption"]),
+  target: z.string().optional(),
+  value: z.unknown(),
+});
+export type CaptionPositionBody = z.infer<typeof captionPositionBody>;
+
+/* POST …/captions/text */
+export const captionTextBody = z.object({ id: z.string(), text: z.string() });
+export type CaptionTextBody = z.infer<typeof captionTextBody>;

package/studio/shared/schemas/carousel.ts

@@ -0,0 +1,26 @@
+/* The content's Instagram carousel (Carousel* stages). */
+
+import { z } from "zod";
+
+/* POST /api/videos/:slug/carousel/create */
+export const carouselCreateBody = z.object({ note: z.string().optional() });
+export type CarouselCreateBody = z.infer<typeof carouselCreateBody>;
+
+/* POST …/carousel/adjust: a change on one slide (sNN) or on the whole carousel */
+export const carouselAdjustBody = z.object({
+  request: z.string(),
+  slide: z.string().optional(),
+  stage: z.enum(["script", "composition"]).optional(),
+});
+export type CarouselAdjustBody = z.infer<typeof carouselAdjustBody>;
+
+/* POST …/carousel/caption */
+export const carouselCaptionBody = z.object({ caption: z.string() });
+export type CarouselCaptionBody = z.infer<typeof carouselCaptionBody>;
+
+/* POST …/carousel/publish: the caption (saved first) and "again" */
+export const carouselPublishBody = z.object({
+  caption: z.string().nullish(),
+  republish: z.boolean().optional(),
+});
+export type CarouselPublishBody = z.infer<typeof carouselPublishBody>;