@crievo/omni 0.0.0-stage → 0.1.0

package/studio/api/services/agent.ts

@@ -0,0 +1,553 @@
+/* Omni, the studio's voice agent, on Grok Voice (xAI realtime, speech to speech). The persona, the
+   greeting, the keyterms and the silence handling live in the agent saved in console.x.ai
+   (`agent.xai_agent_id`); the browser connects to it directly over WebSocket. This side mints the
+   short-lived token (the API key never leaves the machine), picks the voice (Omni is always Omni:
+   the user only chooses a female or a male voice), adds the tools and the session's context, and
+   keeps the log that measures it: latency to the first audio, minutes, tool calls and 👍/👎.
+
+   Config `agent` in omnivideo.config.json:
+   { enabled, xai_agent_id, gender, voices: { female, male }, model, language, idle: { nudge_s, hangup_s },
+     limits: { daily_voice_min, daily_usd, max_session_min, max_actions, max_tool_calls }, wait_max_min }.
+   The persona is agent-persona.ts: the instructions without a console agent, the context message with one.
+   Log: .agent/log.jsonl. */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { AVATAR_SEED } from "../../shared/schemas/agent";
+import { isHotword } from "../../shared/omni-hotword";
+import { OMNI_ENGINES, type OmniEngine, engineOf } from "../../shared/omni-admin";
+import { ROOT, readJson } from "./root";
+import { readEnvKeys } from "./services";
+import { listVideos } from "./videos";
+import { getQueue } from "./queue";
+import { getAnalytics } from "./analytics";
+import { TOOL_DEFS, pendingForUser, registerToolSession } from "./agent-tools";
+import { UI_TOOL_DEFS } from "./agent-ui-tools";
+import { GROK_TOOL_RULES, omniPersona } from "./agent-persona";
+
+export const AGENT_DIR = join(ROOT, ".agent");
+const LOG_FILE = join(AGENT_DIR, "log.jsonl");
+const SAMPLES_DIR = join(AGENT_DIR, "samples");
+const XAI = "https://api.x.ai/v1";
+
+/* Grok Voice is billed per second of open session ($0.08/min); classification per token (classify.ts) */
+export const VOICE_PRICE_PER_MIN = 0.08;
+
+export type AgentGender = "female" | "male";
+/* idle: Grok asks "Ainda tá aí?" after `nudge_s` of silence and the page hangs up after `hangup_s`
+   without the user speaking (with a console agent, its own follow-up settings ask first) */
+/* limits: what a runaway conversation can spend or do (enforced here and in agent-tools.ts) */
+/* daily_voice_min: Grok voice minutes per day; past it, Omni goes on in Claude mode (speech → STT →
+   the user's own Claude, answering in text), which costs almost nothing */
+export type AgentLimits = {
+  daily_voice_min: number;
+  daily_usd: number;
+  max_session_min: number;
+  max_actions: number;
+  max_tool_calls: number;
+};
+export type AgentConfig = {
+  /* false: Omni is off (the widget hides, no session starts) */
+  enabled: boolean;
+  xai_agent_id: string | null;
+  /* what Omni runs on, for every user (the admin panel, agent.engine): Grok Voice or a cascade mode */
+  engine: OmniEngine;
+  gender: AgentGender;
+  /* Omni's face: the seed of its avatar (the studio's Omni settings) */
+  avatar: string;
+  voices: Record<AgentGender, string>;
+  model: string;
+  language: string;
+  idle: { nudge_s: number; hangup_s: number };
+  limits: AgentLimits;
+  /* waiting for the studio's work (wait_for_work, lib/omni-wait.ts): the call sleeps with the
+     microphone open and hangs up for good past this many minutes */
+  wait_max_min: number;
+};
+const DEFAULTS: AgentConfig = {
+  enabled: true,
+  xai_agent_id: null,
+  engine: "grok",
+  gender: "female",
+  avatar: "omni-ara",
+  voices: { female: "ara", male: "rex" },
+  model: "grok-voice-3.0",
+  language: "pt-BR",
+  idle: { nudge_s: 10, hangup_s: 20 },
+  limits: { daily_voice_min: 5, daily_usd: 1, max_session_min: 10, max_actions: 5, max_tool_calls: 40 },
+  wait_max_min: 20,
+};
+const num = (v: unknown, fallback: number, min: number, max: number) =>
+  typeof v === "number" && Number.isFinite(v) && v >= min && v <= max ? v : fallback;
+const seconds = (v: unknown, fallback: number) => (typeof v === "number" && v >= 5 && v <= 600 ? v : fallback);
+const text = (v: unknown, fallback: string) => (typeof v === "string" && v.trim() ? v.trim() : fallback);
+
+/* what a user hears when the admin switched Omni off or moved it to another engine (admin panel) */
+export const OMNI_OFF = "a Omni está desligada pelo admin";
+export const engineMismatch = (engine: OmniEngine) =>
+  `o admin mudou a Omni para ${OMNI_ENGINES.find(e => e.id === engine)?.label ?? engine}: abra a conversa de novo`;
+
+export function agentConfig(): AgentConfig {
+  const cfg = readJson<any>(join(ROOT, "omnivideo.config.json"))?.agent ?? {};
+  const L = DEFAULTS.limits;
+  return {
+    enabled: cfg.enabled !== false,
+    xai_agent_id: typeof cfg.xai_agent_id === "string" && cfg.xai_agent_id ? cfg.xai_agent_id : null,
+    engine: engineOf(cfg),
+    gender: cfg.gender === "male" ? "male" : "female",
+    avatar: typeof cfg.avatar === "string" && AVATAR_SEED.test(cfg.avatar) ? cfg.avatar : DEFAULTS.avatar,
+    voices: {
+      female: text(cfg.voices?.female, DEFAULTS.voices.female),
+      male: text(cfg.voices?.male, DEFAULTS.voices.male),
+    },
+    model: text(cfg.model, DEFAULTS.model),
+    language: text(cfg.language, DEFAULTS.language),
+    idle: {
+      nudge_s: seconds(cfg.idle?.nudge_s, DEFAULTS.idle.nudge_s),
+      hangup_s: seconds(cfg.idle?.hangup_s, DEFAULTS.idle.hangup_s),
+    },
+    limits: {
+      daily_voice_min: num(cfg.limits?.daily_voice_min, L.daily_voice_min, 0, 600),
+      daily_usd: num(cfg.limits?.daily_usd, L.daily_usd, 0, 100),
+      max_session_min: num(cfg.limits?.max_session_min, L.max_session_min, 1, 60),
+      max_actions: num(cfg.limits?.max_actions, L.max_actions, 0, 50),
+      max_tool_calls: num(cfg.limits?.max_tool_calls, L.max_tool_calls, 1, 500),
+    },
+    wait_max_min: num(cfg.wait_max_min, DEFAULTS.wait_max_min, 1, 120),
+  };
+}
+
+function xaiKey(): string {
+  const key = readEnvKeys().XAI_API_KEY;
+  if (!key) throw new Error("falta XAI_API_KEY no .env");
+  return key;
+}
+
+async function xai(path: string, body?: unknown): Promise<Response> {
+  return fetch(`${XAI}${path}`, {
+    method: body === undefined ? "GET" : "POST",
+    headers: { Authorization: `Bearer ${xaiKey()}`, "Content-Type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal: AbortSignal.timeout(20_000),
+  });
+}
+
+/* --- voice sample ------------------------------------------------------------------------------ */
+const SAMPLE_TEXT = "Oi! Eu sou o Omni. Posso ver seus vídeos, as métricas do canal e pedir alterações por você.";
+
+/* what Omni says when the user started a call and said nothing for a while (recorded once, like the sample) */
+const PROMPT_TEXT = "Oi, no que posso ajudar?";
+const CLIPS = { greeting: SAMPLE_TEXT, prompt: PROMPT_TEXT } as const;
+export type VoiceClip = keyof typeof CLIPS;
+
+/* a short pt-BR clip of the female or male voice (xAI TTS), cached in .agent/samples: the greeting that
+   is also the sample ("Ouvir"), or the "no que posso ajudar?" prompt */
+export async function voiceSample(gender: string, clip: string = "greeting"): Promise<string> {
+  if (gender !== "female" && gender !== "male") throw new Error("voz inválida");
+  if (!(clip in CLIPS)) throw new Error("trecho inválido");
+  /* the greeting the user recorded for Omni (Fish, the cascade voice) wins over the xAI sample, for both genders */
+  const chosen = join(SAMPLES_DIR, "greeting.mp3");
+  if (clip === "greeting" && existsSync(chosen)) return chosen;
+  const config = agentConfig();
+  const voice = config.voices[gender];
+  const file = join(SAMPLES_DIR, `${voice.toLowerCase()}${clip === "greeting" ? "" : `-${clip}`}.mp3`);
+  if (existsSync(file)) return file;
+  const r = await xai("/tts", { text: CLIPS[clip as VoiceClip], voice_id: voice, language: config.language });
+  if (!r.ok) throw new Error(`xAI ${r.status}: ${(await r.text()).slice(0, 200)}`);
+  mkdirSync(SAMPLES_DIR, { recursive: true });
+  writeFileSync(file, Buffer.from(await r.arrayBuffer()));
+  return file;
+}
+
+/* --- session ---------------------------------------------------------------------------------- */
+async function snapshot(): Promise<string> {
+  const lines: string[] = [];
+  try {
+    const videos: any[] = (await listVideos(getQueue())).filter((v: any) => !v.archived);
+    videos.sort((a, b) => b.created - a.created);
+    lines.push(`Conteúdos ativos: ${videos.length}. Os mais recentes:`);
+    for (const v of videos.slice(0, 8)) {
+      const next = v.status?.stages?.find((s: any) => !s.ok);
+      const published = ["youtube", "instagram", "tiktok"].filter(p => v.publication?.[p]?.url);
+      lines.push(
+        `- ${v.slug}: "${v.title}" · ${next ? `próxima etapa: ${next.name}` : "pronto"}${published.length ? ` · publicado (${published.join(", ")})` : ""}`,
+      );
+    }
+  } catch {
+    lines.push("(não deu para ler a lista de vídeos agora: use list_videos)");
+  }
+  try {
+    const a = await getAnalytics();
+    const acc = a?.account?.at?.(-1);
+    const m = a?.medians?.current;
+    if (acc) lines.push(`Instagram @${acc.username}: ${acc.followers} seguidores.`);
+    if (m)
+      lines.push(
+        `Mediana dos Reels (n=${m.n}): ${m.views} views, ${m.watched_pct}% assistido, ${m.skip_3s_pct}% pulam nos 3 s.`,
+      );
+  } catch {
+    /* metrics are optional */
+  }
+  /* what waits for the user, so Omni knows it before anyone asks */
+  try {
+    const w = await pendingForUser();
+    lines.push(
+      w.count
+        ? `Esperando o usuário (${w.count}): ${w.items
+            .map(
+              i => `${i.label} em ${i.slug}${i.auto_in_min != null ? ` (aprova sozinho em ${i.auto_in_min} min)` : ""}`,
+            )
+            .join("; ")}. Para abrir, navigate com o slug e a etapa (stage) de pending_approvals.`
+        : "Nada esperando aprovação do usuário agora.",
+    );
+  } catch {
+    /* the list is optional: pending_approvals reads it again */
+  }
+  return lines.join("\n");
+}
+
+/* what changes every session: the time and the studio's state, sent as a system message */
+export async function sessionContext(now: Date): Promise<string> {
+  return `Agora são ${now.toLocaleString("pt-BR", { timeZone: "America/Sao_Paulo" })} (horário de Brasília).
+
+Estado do estúdio no começo da conversa (para o resto, use as ferramentas):
+${await snapshot()}`;
+}
+
+export type AgentSession = {
+  id: string;
+  token: string;
+  expires_at: number;
+  url: string;
+  /* the session.update sent right after connecting; with a console agent it only adds to it
+     (voice, audio format, tools), so the console's persona and silence settings stay */
+  session: Record<string, unknown>;
+  /* the system message sent after it: the time and the studio's state */
+  context: string;
+  config: AgentConfig;
+  /* what is left of today's voice quota: the page hangs up and switches to Claude mode at zero */
+  voice_remaining_s: number;
+};
+
+const brl = (v: number) => v.toFixed(2).replace(".", ",");
+
+/* Grok sessions minted since the studio started: only these can be resumed after a wait */
+const grokSessions = new Set<string>();
+
+/* `resume`: the call slept waiting for the studio's work (wait_for_work) and wakes up. Same session
+   id (its tool limits and staged cards go on), a new token and a fresh context; the minutes it slept
+   are not voice minutes (each open stretch logs its own "end", see usageToday) */
+export async function startSession(resume?: string): Promise<AgentSession> {
+  if (resume && !grokSessions.has(resume)) throw new Error("essa conversa não existe mais: comece outra");
+  const config = agentConfig();
+  if (!config.enabled) throw new Error(OMNI_OFF);
+  if (config.engine !== "grok") throw new Error(engineMismatch(config.engine));
+  const remaining = voiceRemainingSeconds(config);
+  if (remaining <= 0) throw new QuotaError(config.limits.daily_voice_min);
+  const spent = spentToday();
+  if (spent >= config.limits.daily_usd)
+    throw new Error(
+      `limite diário do Omni atingido: US$ ${brl(spent)} de US$ ${brl(config.limits.daily_usd)} (agent.limits.daily_usd)`,
+    );
+  /* the token only opens the WebSocket: a short life is enough */
+  const r = await xai("/realtime/client_secrets", { expires_after: { seconds: 60 } });
+  if (!r.ok) throw new Error(`xAI ${r.status}: ${(await r.text()).slice(0, 200)}`);
+  const secret: any = await r.json();
+  const id =
+    resume ?? `${new Date().toISOString().slice(0, 19).replace(/[-:T]/g, "")}-${crypto.randomUUID().slice(0, 6)}`;
+  const voice = config.voices[config.gender];
+  const audio = {
+    input: { format: { type: "audio/pcm", rate: 24000 }, transcription: { language_hint: config.language } },
+    output: { format: { type: "audio/pcm", rate: 24000 } },
+  };
+  /* the tools replace the console's (its end_call included): end_call is in TOOL_DEFS; the UI tools
+     (navigate…) run in the browser (lib/omni-ui); web_search is xAI's own, run on their side */
+  const tools = [...TOOL_DEFS, ...UI_TOOL_DEFS, { type: "web_search" }];
+  const session = config.xai_agent_id
+    ? { voice, audio, tools }
+    : {
+        voice,
+        instructions: `${omniPersona(config.gender)}\n\n${GROK_TOOL_RULES}`,
+        turn_detection: { type: "server_vad", idle_timeout_ms: config.idle.nudge_s * 1000 },
+        audio,
+        tools,
+      };
+  if (resume) logEvent({ session: id, type: "resume" });
+  else {
+    registerToolSession(id, { max_actions: config.limits.max_actions, max_tool_calls: config.limits.max_tool_calls });
+    grokSessions.add(id);
+    logEvent({ session: id, type: "start", voice, model: config.model, agent: config.xai_agent_id });
+  }
+  return {
+    id,
+    token: secret.value,
+    expires_at: secret.expires_at,
+    url: config.xai_agent_id
+      ? `wss://api.x.ai/v1/realtime?agent_id=${encodeURIComponent(config.xai_agent_id)}`
+      : `wss://api.x.ai/v1/realtime?model=${encodeURIComponent(config.model)}`,
+    session,
+    /* with a console agent, the persona rides in the context message: the console keeps the greeting,
+       the speed and the silence settings, and the rules stay the same as the cascade's */
+    context: config.xai_agent_id
+      ? `${omniPersona(config.gender)}\n\n${GROK_TOOL_RULES}\n\n${await sessionContext(new Date())}`
+      : await sessionContext(new Date()),
+    config,
+    voice_remaining_s: Math.floor(remaining),
+  };
+}
+
+/* the voice quota for today is used up: the page switches to Claude mode */
+export class QuotaError extends Error {
+  constructor(minutes: number) {
+    super(`a cota de voz de hoje acabou (${minutes} min): sigo por texto com o Claude`);
+  }
+}
+
+export function voiceRemainingSeconds(config = agentConfig()): number {
+  return config.limits.daily_voice_min * 60 - usageToday().voice_s;
+}
+
+/* --- log and stats ----------------------------------------------------------------------------- */
+export type AgentEvent = { session: string; type: string; [k: string]: unknown };
+
+export function logEvent(e: AgentEvent) {
+  mkdirSync(AGENT_DIR, { recursive: true });
+  appendFileSync(LOG_FILE, `${JSON.stringify({ at: new Date().toISOString(), ...e })}\n`);
+}
+
+/* a card decided by voice (confirm_action, cancel_action): the same "action" line as the buttons */
+export function logResolved(session: string, output: Record<string, unknown>) {
+  const r = output.resolved as { kind: string; slug: string | null; summary: string; state: string } | undefined;
+  if (!r) return;
+  logEvent({
+    session,
+    type: "action",
+    kind: r.kind,
+    slug: r.slug,
+    summary: r.summary,
+    via: "voice",
+    ...(r.state === "canceled"
+      ? { canceled: true }
+      : { ok: r.state === "confirmed", error: typeof output.error === "string" ? output.error : undefined }),
+  });
+}
+
+function readLog(): (AgentEvent & { at: string })[] {
+  try {
+    return readFileSync(LOG_FILE, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .map(l => JSON.parse(l));
+  } catch {
+    return [];
+  }
+}
+
+/* what Omni used today (local day): Grok voice seconds by session time, the sum of its open stretches
+   (a call that slept waiting for the studio's work logs an "end" per stretch and a "resume" when it
+   wakes; a stretch with no "end", a closed tab, counts until its last logged event; cascade sessions
+   don't bill by the minute),
+   classification, transcription and the cascade's LLM and paid TTS in dollars */
+export function usageToday(): { voice_s: number; classify_usd: number; stt_usd: number; cascade_usd: number } {
+  const today = new Date().toDateString();
+  const log = readLog().filter(e => new Date(e.at).toDateString() === today);
+  const bySession = new Map<string, { openAt: number | null; last: number; duration: number; voice: boolean }>();
+  let classify = 0;
+  let stt = 0;
+  let cascade = 0;
+  for (const e of log) {
+    const t = Date.parse(e.at);
+    if (e.type === "tool") classify += Number(e.cost_usd) || 0;
+    if (e.type === "stt") stt += Number(e.cost_usd) || 0;
+    if (e.type === "llm" || e.type === "tts") cascade += Number(e.cost_usd) || 0;
+    if (e.session === "-" || e.type === "stt" || e.type === "claude") continue;
+    const s = bySession.get(e.session) ?? { openAt: t, last: t, duration: 0, voice: false };
+    if (e.type === "start") s.voice = !e.mode || e.mode === "grok";
+    if (e.type === "start" || e.type === "resume") s.openAt = t;
+    s.last = Math.max(s.last, t);
+    if (e.type === "end") {
+      s.duration += Number(e.duration_s) || 0;
+      s.openAt = null;
+    }
+    bySession.set(e.session, s);
+  }
+  let seconds = 0;
+  for (const s of bySession.values())
+    if (s.voice) seconds += s.duration + (s.openAt != null ? (s.last - s.openAt) / 1000 : 0);
+  return { voice_s: seconds, classify_usd: classify, stt_usd: stt, cascade_usd: cascade };
+}
+
+export function spentToday(): number {
+  const u = usageToday();
+  return (u.voice_s / 60) * VOICE_PRICE_PER_MIN + u.classify_usd + u.stt_usd + u.cascade_usd;
+}
+
+/* --- Claude mode: speech to text ---------------------------------------------------------------- */
+/* grok-voice-transcribe: $0.10 per hour of audio */
+const STT_PRICE_PER_S = 0.1 / 3600;
+
+/* raw PCM16 mono 24 kHz from the page's microphone (base64) → text */
+export async function transcribe(pcmBase64: string, session: string): Promise<{ text: string; duration: number }> {
+  const pcm = Buffer.from(pcmBase64, "base64");
+  if (pcm.length < 24000 * 2 * 0.3) throw new Error("áudio curto demais");
+  if (pcm.length > 24000 * 2 * 120) throw new Error("áudio longo demais (máximo 2 minutos)");
+  const form = new FormData();
+  form.append("model", "grok-voice-transcribe-2.0");
+  form.append("language", agentConfig().language);
+  form.append("audio_format", "pcm");
+  form.append("sample_rate", "24000");
+  form.append("file", new Blob([pcm]), "speech.pcm");
+  const r = await fetch(`${XAI}/stt`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${xaiKey()}` },
+    body: form,
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!r.ok) throw new Error(`xAI ${r.status}: ${(await r.text()).slice(0, 200)}`);
+  const j: any = await r.json();
+  const duration = Number(j.duration) || pcm.length / 48000;
+  logEvent({ session, type: "stt", duration_s: Math.round(duration * 10) / 10, cost_usd: duration * STT_PRICE_PER_S });
+  return { text: String(j.text ?? "").trim(), duration };
+}
+
+/* --- "Oi, Omni" -------------------------------------------------------------------------------------
+   With the panel closed, the page (lib/omni-hotword.ts) sends the start of each utterance that follows a
+   pause; it is transcribed here and checked for Omni's name (shared/omni-hotword.ts). The text is not
+   kept nor sent back. A cap on the audio sent per day (`agent.hotword.daily_min`, default 20 min, about
+   $0.03) keeps a talkative day cheap; it also counts in daily_usd, like any transcription. */
+const HOTWORD_SESSION = "hotword";
+
+function hotwordDailyMin(): number {
+  const cfg = readJson<any>(join(ROOT, "omnivideo.config.json"))?.agent?.hotword ?? {};
+  return num(cfg.daily_min, 20, 0, 600);
+}
+
+function hotwordSecondsToday(): number {
+  const today = new Date().toDateString();
+  return readLog()
+    .filter(e => e.session === HOTWORD_SESSION && e.type === "stt" && new Date(e.at).toDateString() === today)
+    .reduce((n, e) => n + (Number(e.duration_s) || 0), 0);
+}
+
+export async function checkHotword(pcmBase64: string): Promise<{ called: boolean }> {
+  const cfg = agentConfig();
+  if (!cfg.enabled) throw new Error(OMNI_OFF);
+  const daily = hotwordDailyMin();
+  if (hotwordSecondsToday() >= daily * 60) throw new HotwordLimit(daily);
+  if (spentToday() >= cfg.limits.daily_usd) throw new HotwordLimit(daily, true);
+  const { text } = await transcribe(pcmBase64, HOTWORD_SESSION);
+  const called = isHotword(text);
+  if (called) logEvent({ session: HOTWORD_SESSION, type: "hotword" });
+  return { called };
+}
+
+export class HotwordLimit extends Error {
+  constructor(minutes: number, spend = false) {
+    super(
+      spend
+        ? "o gasto de hoje da Omni chegou ao limite: o “Oi, Omni” volta amanhã"
+        : `o “Oi, Omni” já ouviu ${minutes} min hoje: volta amanhã`,
+    );
+  }
+}
+
+const quantile = (xs: number[], q: number) => {
+  if (!xs.length) return null;
+  const s = [...xs].sort((a, b) => a - b);
+  return s[Math.min(s.length - 1, Math.floor(q * s.length))];
+};
+
+export type AgentStats = {
+  sessions: number;
+  minutes: number;
+  turns: number;
+  latency_p50_ms: number | null;
+  latency_p90_ms: number | null;
+  tool_calls: number;
+  tool_errors: number;
+  classify_cost_usd: number;
+  voice_cost_usd: number;
+  thumbs_up: number;
+  thumbs_down: number;
+  by_mode: AgentModeStats[];
+};
+
+export function agentStats(): AgentStats {
+  const log = readLog();
+  const sessions = new Set(log.filter(e => e.type === "start").map(e => e.session));
+  /* only Grok bills the open minute: cascade sessions (start with a mode) don't count as voice */
+  const cascade = new Set(log.filter(e => e.type === "start" && e.mode && e.mode !== "grok").map(e => e.session));
+  const ends = log.filter(e => e.type === "end" && !cascade.has(e.session));
+  const seconds = ends.reduce((n, e) => n + (Number(e.duration_s) || 0), 0);
+  const latencies = log
+    .filter(e => e.type === "turn" && typeof e.latency_ms === "number")
+    .map(e => e.latency_ms as number);
+  const tools = log.filter(e => e.type === "tool");
+  /* the last vote per reply wins (switching 👍 to 👎) */
+  const votes = new Map<string, string>();
+  for (const e of log.filter(e => e.type === "feedback")) votes.set(`${e.session}:${e.item}`, String(e.value));
+  return {
+    sessions: sessions.size,
+    minutes: Math.round((seconds / 60) * 10) / 10,
+    turns: latencies.length,
+    latency_p50_ms: quantile(latencies, 0.5),
+    latency_p90_ms: quantile(latencies, 0.9),
+    tool_calls: tools.length,
+    tool_errors: tools.filter(e => e.error).length,
+    classify_cost_usd:
+      tools.reduce((n, e) => n + (Number(e.cost_usd) || 0), 0) +
+      log
+        .filter(e => e.type === "stt" || e.type === "llm" || e.type === "tts")
+        .reduce((n, e) => n + (Number(e.cost_usd) || 0), 0),
+    voice_cost_usd: (seconds / 60) * VOICE_PRICE_PER_MIN,
+    thumbs_up: [...votes.values()].filter(v => v === "up").length,
+    thumbs_down: [...votes.values()].filter(v => v === "down").length,
+    by_mode: statsByMode(log, votes),
+  };
+}
+
+export type AgentModeStats = {
+  mode: "grok" | "stream" | "chunks";
+  sessions: number;
+  minutes: number;
+  turns: number;
+  latency_p50_ms: number | null;
+  latency_p90_ms: number | null;
+  cost_usd: number;
+  cost_per_min_usd: number | null;
+  thumbs_up: number;
+  thumbs_down: number;
+};
+
+/* each conversation by how it talked (its start: no mode is Grok, from before the cascade), with what
+   it cost: Grok bills its open minutes, the cascade its STT, LLM and paid TTS; tools on top of both */
+function statsByMode(log: (AgentEvent & { at: string })[], votes: Map<string, string>): AgentModeStats[] {
+  const modeOf = new Map<string, AgentModeStats["mode"]>();
+  for (const e of log)
+    if (e.type === "start") modeOf.set(e.session, e.mode === "stream" || e.mode === "chunks" ? e.mode : "grok");
+  return (["grok", "stream", "chunks"] as const).map(mode => {
+    const mine = (e: AgentEvent) => modeOf.get(e.session) === mode;
+    const seconds = log.filter(e => e.type === "end" && mine(e)).reduce((n, e) => n + (Number(e.duration_s) || 0), 0);
+    const latencies = log
+      .filter(e => e.type === "turn" && mine(e) && typeof e.latency_ms === "number")
+      .map(e => e.latency_ms as number);
+    const billed = log
+      .filter(e => mine(e) && (e.type === "tool" || e.type === "stt" || e.type === "llm" || e.type === "tts"))
+      .reduce((n, e) => n + (Number(e.cost_usd) || 0), 0);
+    const cost = billed + (mode === "grok" ? (seconds / 60) * VOICE_PRICE_PER_MIN : 0);
+    const myVotes = [...votes.entries()].filter(([k]) => modeOf.get(k.split(":")[0]) === mode).map(([, v]) => v);
+    const minutes = seconds / 60;
+    return {
+      mode,
+      sessions: [...modeOf.values()].filter(m => m === mode).length,
+      minutes: Math.round(minutes * 10) / 10,
+      turns: latencies.length,
+      latency_p50_ms: quantile(latencies, 0.5),
+      latency_p90_ms: quantile(latencies, 0.9),
+      cost_usd: cost,
+      cost_per_min_usd: minutes > 0 ? cost / minutes : null,
+      thumbs_up: myVotes.filter(v => v === "up").length,
+      thumbs_down: myVotes.filter(v => v === "down").length,
+    };
+  });
+}

package/studio/api/services/analytics.ts

@@ -0,0 +1,92 @@
+/* Analytics: the metrics of the published Reels and Claude's analysis of
+   them. The numbers live in tools/metrics.mjs (the launchd agent collects them
+   every 4 hours) and tools/analysis.mjs gathers account, medians, script
+   strategy and hook; the studio only shows what it returns, like voice usage.
+   Collection is every 4 hours, and each Reel's series comes in its detail.
+   The analysis is the av-analysis skill, in a studio session of its own (type
+   "analysis", target "channel"): it writes videos/<slug>/analysis.md,
+   channel/analyses/<day>.md and updates channel/playbook.md. */
+
+import { join } from "node:path";
+import { NODE, ROOT, TOOLS_DIR, run, readText, readJson } from "./root";
+import { videoDirs } from "./videos";
+import { openSession, replyToSession, latestSessionFor, type ApiResult } from "./sessions";
+
+const METRICS = join(TOOLS_DIR, "metrics.mjs");
+const ANALYSIS = join(TOOLS_DIR, "analysis.mjs");
+export const CHANNEL_DIR = join(ROOT, "channel");
+
+/* account, medians and each Reel; the UI only rereads on the "analytics" notice (events.ts), so
+   there is no cache: the file that just changed is what comes back */
+export async function getAnalytics(): Promise<any> {
+  const r = await run([NODE, ANALYSIS, "context"]);
+  if (r.code !== 0) return { error: r.stderr.trim().split("\n").pop() || `analysis.mjs saiu com código ${r.code}` };
+  try {
+    const data = JSON.parse(r.stdout);
+    const last = data.last_analysis;
+    if (last) last.text = readText(join(ROOT, last.file));
+    return data;
+  } catch {
+    return { error: "analysis.mjs devolveu algo que não é JSON" };
+  }
+}
+
+/* one Reel: what the context has on it, the series of readings (the detail's wave line) and
+   analysis.md, if the skill already wrote it */
+export async function getReel(slug: string): Promise<any> {
+  const d = await getAnalytics();
+  if (d.error) return d;
+  const v = d.videos.find((x: any) => x.slug === slug);
+  if (!v) return null;
+  const dir = videoDirs().get(slug);
+  const hourly = dir ? (readJson<any>(join(dir, "metrics.json"))?.instagram?.hourly ?? []) : [];
+  return { ...v, hourly, medians: d.medians, analysis_text: dir ? readText(join(dir, "analysis.md")) : null };
+}
+
+/* reads the API now (GET only; nothing changes on Instagram) and redoes everyone's current reading */
+export async function collectMetrics(): Promise<ApiResult> {
+  const r = await run([NODE, METRICS, "collect", "--force"]);
+  if (r.code !== 0) return { ok: false, error: (r.stderr || r.stdout).trim().split("\n").pop() || "a coleta falhou" };
+  return { ok: true, output: r.stdout.trim() ? "métricas lidas agora" : "nada para ler" };
+}
+
+/* enables and disables the launchd agent (collection every 4 hours): installs with the studio's node */
+export async function setMetricsAgent(enable: unknown): Promise<ApiResult> {
+  const r = await run([NODE, METRICS, "agent", enable ? "install" : "uninstall"]);
+  if (r.code !== 0) return { ok: false, error: (r.stderr || r.stdout).trim() };
+  return { ok: true, output: r.stdout.trim() };
+}
+
+/* "Gerar análise": of the channel, or of one Reel (`slug`). With a stopped analysis session, it
+   resumes with the new request and remembers the previous analyses; without one, opens one. */
+export function requestAnalysis(body: { slug?: unknown; focus?: unknown }): ApiResult {
+  const slug = String(body.slug ?? "").trim();
+  if (slug && !videoDirs().has(slug)) return { ok: false, error: "vídeo não encontrado" };
+  const focus = String(body.focus ?? "").trim();
+  const prompt = [
+    `/av-analysis ${slug ? `videos/${slug}` : "channel"}${focus ? ` foco: ${focus}` : ""}`,
+    slug
+      ? `Pedido pela tela Analytics do studio: analise só o Reel videos/${slug} (o analysis.md dele; o playbook só se ele muda um aprendizado).`
+      : "Pedido pela tela Analytics do studio: analise o canal inteiro (cada Reel que mudou, os insights e o plano dos próximos vídeos, e o playbook).",
+    "No fim, responda em poucas linhas: o achado principal e os próximos passos. O usuário lê na tela Analytics.",
+  ].join("\n");
+  const last = latestSessionFor("analysis", "channel");
+  if (last) return replyToSession(last.id, prompt, "request");
+  return openSession("analysis", "channel", CHANNEL_DIR, "Análise do canal", prompt);
+}
+
+/* reply written in the Analytics page's Claude panel */
+export function chatAnalysis(message: unknown): ApiResult {
+  const text = String(message ?? "").trim();
+  const last = latestSessionFor("analysis", "channel");
+  if (last) return replyToSession(last.id, text || "Continue de onde parou.", text ? "user" : "resume");
+  if (!text) return { ok: false, error: "diga o que quer saber das métricas" };
+  return openSession(
+    "analysis",
+    "channel",
+    CHANNEL_DIR,
+    "Análise do canal",
+    `Pergunta feita pela tela Analytics do studio sobre as métricas do canal: ${text}\nUse \`node tools/analysis.mjs context\` e o channel/playbook.md; para análise completa, a skill av-analysis.`,
+    "user",
+  );
+}