@crievo/omni 0.0.0-stage → 0.1.1

package/studio/api/services/voices.ts

@@ -0,0 +1,324 @@
+/* Readings of a line from the UI: generate another (`voice --regenerate`) and choose
+   which one counts for the video (`voice --use`). omnivideo.py writes them, the same
+   the chat would call; the reading that leaves goes to history/voice/<line>/.
+
+   Generating waits for its turn in the queue (may take a while if the machine is busy): the
+   process runs on its own and the UI follows it through the queue. Only errors before the
+   queue (missing line, no provider) come back in the response.
+
+   The line text is also edited here (`text` in scenes.json). A line that already has
+   a voice gets the new reading right away: text and audio never diverge.
+   Text that removes a beat's word becomes a request to the video's Claude, which changes
+   the line and the beat together.
+
+   Removing takes the line out of the narration (a sentence split in two that the user wants
+   as one) and asks the video's Claude for the beats that depended on it and what comes
+   after timing.
+
+   Every voice change pauses what comes after it (voice-pause.ts) until the user
+   clicks "Seguir com estas vozes" (`proceedWithVoices`). */
+
+import { writeFileSync, renameSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { PYTHON, ROOT, TOOLS_DIR, run, readJson } from "./root";
+import { getQueue } from "./queue";
+import { chatWith } from "./create";
+import { latestSessionFor } from "./sessions";
+import { pauseAfterVoice, interruptAfterVoice, pauseNotice, readPause, PAUSE_FILE } from "./voice-pause";
+import { keepPrevious } from "../../../tools/history.mjs";
+
+type Result = { ok: true; output: string } | { ok: false; error: string };
+
+const OMNIVIDEO = join(TOOLS_DIR, "omnivideo.py");
+const LINE_ID = /^c\d+f\d+$/;
+const VERSION = /^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z$/;
+
+function lineExists(dir: string, line: string) {
+  const scenes = readJson<any>(join(dir, "scenes.json"));
+  return (scenes?.scenes ?? []).some((c: any) => (c.lines ?? []).some((l: any) => l.id === line));
+}
+
+const voiceTicketOf = (dir: string) => {
+  const q = getQueue();
+  return [...q.running, ...q.waiting].find(s => s.dir === dir && s.tool === "voice");
+};
+
+/* `omnivideo.py voice`: exits right away if something is missing before the queue; then runs on its own */
+async function runVoice(dir: string, args: string[], generating: string): Promise<Result> {
+  const p = Bun.spawn([PYTHON, OMNIVIDEO, "voice", dir, ...args], {
+    cwd: ROOT,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env, OMNIVIDEO_ORIGIN: "studio" },
+  });
+  const output = Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text()]);
+  const early = await Promise.race([p.exited, Bun.sleep(2500).then(() => null)]);
+  if (early !== null && early !== 0) {
+    const [o, e] = await output;
+    return { ok: false, error: (e || o).trim() || `omnivideo.py saiu com ${early}` };
+  }
+  return { ok: true, output: early === 0 ? (await output)[0].trim() : generating };
+}
+
+/* another reading of a single line: `--regenerate` generates that one and no other, even if the
+   video's provider changed and the other lines are still from the old one */
+export async function regenerateLine(dir: string, line: string, provider?: string): Promise<Result> {
+  if (!LINE_ID.test(line) || !lineExists(dir, line)) return { ok: false, error: `a fala ${line} não existe` };
+  /* `provider` is for this line only (omnivideo.py `--provider`): the video's doesn't change */
+  if (provider && !/^[a-z]+$/.test(provider)) return { ok: false, error: `provider inválido: ${provider}` };
+  const pause = pauseAfterVoice(dir, [line]);
+  const r = await runVoice(
+    dir,
+    ["--regenerate", line, ...(provider ? ["--provider", provider] : [])],
+    `${line}: gerando outra fala (acompanhe na etapa Voz ou na fila)`,
+  );
+  return r.ok ? { ok: true, output: `${r.output}; ${pauseNotice(pause)}` } : r;
+}
+
+/* every line not yet in the video's provider (`voice` with no arguments:
+   missing audio, changed text or changed requested provider). What is up to date is not redone. */
+export async function generateAllLines(dir: string): Promise<Result> {
+  if (voiceTicketOf(dir)) return { ok: false, error: "a voz deste vídeo já está sendo gerada: espere terminar" };
+  const pause = pauseAfterVoice(dir, ["all"]);
+  const r = await runVoice(dir, [], "gerando as falas com a voz do vídeo (acompanhe na etapa Voz ou na fila)");
+  return r.ok ? { ok: true, output: `${r.output}; ${pauseNotice(pause)}` } : r;
+}
+
+/* every line again, even the up-to-date ones: that's what a voice (profile) change needs, since the
+   provider and the text are the same and `voice` with no arguments sees nothing to redo. Uses the
+   video's provider (the main select's); without `--provider`, each line follows the video again (`provider_pinned` drops). */
+export async function regenerateAllLines(dir: string): Promise<Result> {
+  if (voiceTicketOf(dir)) return { ok: false, error: "a voz deste vídeo já está sendo gerada: espere terminar" };
+  const scenes = readJson<any>(join(dir, "scenes.json"));
+  const ids: string[] = (scenes?.scenes ?? []).flatMap((c: any) => (c.lines ?? []).map((l: any) => String(l.id)));
+  if (!ids.length) return { ok: false, error: "o vídeo ainda não tem falas" };
+  const pause = pauseAfterVoice(dir, ["all"]);
+  const r = await runVoice(
+    dir,
+    ["--regenerate", ids.join(",")],
+    `regerando as ${ids.length} falas com a voz do vídeo (acompanhe na etapa Voz ou na fila)`,
+  );
+  return r.ok ? { ok: true, output: `${r.output}; ${pauseNotice(pause)}` } : r;
+}
+
+/* the same word rule as tools/timing.mjs */
+const norm = (w: string) =>
+  w
+    .toLowerCase()
+    .normalize("NFC")
+    .replace(/[^\p{L}\p{N}]/gu, "");
+const REF = /^([^:+-]+)(?::([^+\-#]+)(?:#(\d+))?)?([+-]\d+(?:\.\d+)?)?$/;
+
+/* the scene's beats that enter on a word of this line the new text no longer has */
+function brokenBeats(scene: any, line: string, text: string) {
+  const words = text.split(/\s+/).map(norm);
+  return (scene.beats ?? []).flatMap((b: any) => {
+    const m = REF.exec(String(b.enters_with ?? "").trim());
+    /* `fim`: legacy alias of `end` */
+    if (!m || m[1] !== line || !m[2] || m[2] === "end" || m[2] === "fim") return [];
+    const times = words.filter(w => w === norm(m[2])).length;
+    return times >= Number(m[3] ?? 1) ? [] : [`${b.element} (entra com “${m[2]}”${m[3] ? ` #${m[3]}` : ""})`];
+  });
+}
+
+/* the new text removes a beat's word: the line and the beat change together, and
+   the video session's Claude picks the new word (av-narration rule) */
+async function askAgent(
+  dir: string,
+  slug: string,
+  line: string,
+  text: string,
+  broken: string[],
+  hasVoice: boolean,
+): Promise<Result> {
+  const message = [
+    `Troquei pela tela o texto da fala ${line} para, palavra por palavra: «${text}».`,
+    `O texto novo não tem mais a palavra em que entra: ${broken.join(", ")}.`,
+    `Grave esse texto exato no scenes.json (não reescreva a fala) e, para cada beat desses, escolha no texto novo a palavra que melhor dispara o que ele mostra e atualize o enters_with, pela regra da av-narration.`,
+    hasVoice
+      ? `A fala já tinha voz: gere a leitura do texto novo com \`${PYTHON} tools/omnivideo.py voice ${dir} --regenerate ${line}\` e pare aí. O vídeo está pausado (voice-pause.json) até eu clicar em "Seguir com estas vozes": não rode tempo, render, legenda nem montagem.`
+      : "A fala ainda não tem voz: só texto e beat, sem gerar nada.",
+    "No fim, diga em uma linha qual palavra cada beat passou a usar.",
+  ].join("\n");
+  await waitAgentStopped(slug);
+  const r = chatWith("video", slug, message);
+  if (!r.ok)
+    return {
+      ok: false,
+      error: `o texto novo tira a palavra em que um beat entra (${broken.join(", ")}), e o agente não pôde ajustar agora: ${r.error}`,
+    };
+  return {
+    ok: true,
+    output: `o texto novo tira a palavra em que um beat entra (${broken.join(", ")}): pedi ao agente para gravar o texto e mudar o beat junto. Acompanhe na sessão do vídeo.`,
+  };
+}
+
+export async function editLineText(dir: string, slug: string, line: string, value: unknown): Promise<Result> {
+  if (!LINE_ID.test(line)) return { ok: false, error: `a fala ${line} não existe` };
+  const text = typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "";
+  if (!text) return { ok: false, error: "o texto da fala não pode ficar vazio" };
+  if (text.length > 600) return { ok: false, error: "texto longo demais para uma fala: divida em duas com o agente" };
+  if (voiceTicketOf(dir))
+    return { ok: false, error: "a voz deste vídeo está sendo gerada agora: edite quando ela terminar" };
+
+  const file = join(dir, "scenes.json");
+  const scenes = readJson<any>(file);
+  const scene = (scenes?.scenes ?? []).find((c: any) => (c.lines ?? []).some((l: any) => l.id === line));
+  if (!scene) return { ok: false, error: `a fala ${line} não existe` };
+  const l = scene.lines.find((x: any) => x.id === line);
+  const hasVoice = !!l.wav;
+  if (hasVoice) pauseAfterVoice(dir, [line]);
+  if (l.text === text) return hasVoice ? regenerateLine(dir, line) : { ok: true, output: "o texto já era este" };
+  const broken = brokenBeats(scene, line, text);
+  if (broken.length) return askAgent(dir, slug, line, text, broken, hasVoice);
+
+  l.text = text;
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(scenes, null, 2) + "\n");
+  renameSync(tmp, file);
+  const n = text.split(" ").length;
+  const warning = n > 22 ? ` (⚠ ${n} palavras: a narração pede até 22 por fala)` : "";
+  if (!hasVoice) return { ok: true, output: `texto gravado${warning}` };
+  const r = await regenerateLine(dir, line);
+  return r.ok
+    ? { ok: true, output: `texto gravado${warning}; ${r.output}` }
+    : { ok: false, error: `o texto foi gravado, mas a voz não saiu: ${r.error}` };
+}
+
+/* beats that enter on a line that no longer exists (removed from the UI) */
+function orphanBeats(scenes: any) {
+  const ids = new Set((scenes?.scenes ?? []).flatMap((c: any) => (c.lines ?? []).map((l: any) => l.id)));
+  return (scenes?.scenes ?? []).flatMap((c: any) =>
+    (c.beats ?? []).flatMap((b: any) => {
+      const m = REF.exec(String(b.enters_with ?? "").trim());
+      return m && LINE_ID.test(m[1]) && !ids.has(m[1]) ? [`${c.id} ${b.element} (entrava com ${b.enters_with})`] : [];
+    }),
+  );
+}
+
+/* what Claude needs to know about removed lines: don't recreate them and change the beats that depended on them */
+function removedLinesRequest(scenes: any, removed: string[]) {
+  const beats = orphanBeats(scenes);
+  return [
+    `Não recrie, não renumere e não gere voz para ${removed.length > 1 ? "essas falas" : "essa fala"}, nem reescreva as que ficaram.`,
+    ...(beats.length
+      ? [
+          `Estes beats entravam numa fala removida: ${beats.join(", ")}. Para cada um, escolha nas falas que ficaram na cena a palavra que melhor dispara o que ele mostra e atualize só o enters_with, pela regra da av-narration.`,
+        ]
+      : []),
+  ];
+}
+
+/* takes a line out of the narration (the sentence the narration split in two and the user wants as one): it leaves
+   scenes.json, the reading goes to history/voice/<line>/ and the video's Claude redoes from timing on.
+   With the video paused (voices being chosen), the removal joins the pause and reaches Claude through "Seguir". */
+export async function removeLine(dir: string, slug: string, line: string): Promise<Result> {
+  if (!LINE_ID.test(line)) return { ok: false, error: `a fala ${line} não existe` };
+  if (voiceTicketOf(dir))
+    return { ok: false, error: "a voz deste vídeo está sendo gerada agora: remova quando ela terminar" };
+
+  const file = join(dir, "scenes.json");
+  const scenes = readJson<any>(file);
+  const scene = (scenes?.scenes ?? []).find((c: any) => (c.lines ?? []).some((l: any) => l.id === line));
+  if (!scene) return { ok: false, error: `a fala ${line} não existe` };
+  if (scene.lines.length === 1)
+    return {
+      ok: false,
+      error: `${line} é a única fala da cena ${scene.id}, e cena sem fala não tem tempo: para tirar a cena, peça ao agente`,
+    };
+  const l = scene.lines.find((x: any) => x.id === line);
+
+  const files = [...new Set([l.wav, `voice/${line}.wav`, `voice/${line}.json`].filter(Boolean))] as string[];
+  keepPrevious(dir, "voice", line, files).close({ keep: true });
+  for (const a of files) rmSync(join(dir, a), { force: true });
+  scene.lines = scene.lines.filter((x: any) => x !== l);
+  /* without the line, the scene lasts something else: `status` asks for timing again */
+  delete scene.duration;
+  /* edited position and text of the removed line's captions */
+  for (const k of ["individual", "texts"]) {
+    const o = scenes.captions?.[k];
+    if (o) for (const key of Object.keys(o)) if (key.startsWith(`${line}.`)) delete o[key];
+  }
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(scenes, null, 2) + "\n");
+  renameSync(tmp, file);
+
+  if (readPause(dir)) {
+    const pause = pauseAfterVoice(dir, [], [line]);
+    return {
+      ok: true,
+      output: `${line} saiu da narração; ${pauseNotice(pause)}: o agente ajusta os beats e refaz o vídeo quando você seguir`,
+    };
+  }
+  const { interrupted } = interruptAfterVoice(dir);
+  await waitAgentStopped(slug);
+  const message = [
+    `Tirei pela tela a fala ${line} da cena ${scene.id} («${l.text}»): saiu do scenes.json, e a leitura foi para history/voice/${line}/.`,
+    ...removedLinesRequest(scenes, [line]),
+    "Depois refaça o vídeo a partir do tempo, como na linha “fala removida” da tabela Retomar ou refazer da skill omnivideo: tempo, render das cenas afetadas, legenda e montagem.",
+  ].join("\n");
+  const r = chatWith("video", slug, message);
+  if (!r.ok) {
+    /* without Claude, the pause holds the video and "Seguir" carries the request */
+    pauseAfterVoice(dir, [], [line]);
+    return {
+      ok: false,
+      error: `${line} saiu da narração, mas o agente não pôde refazer agora (${r.error}): "Seguir com estas vozes" leva o pedido de novo`,
+    };
+  }
+  return {
+    ok: true,
+    output: `${line} saiu da narração${interrupted.length ? ` (parei ${interrupted.join(", ")})` : ""}: o agente ajusta os beats e refaz tempo, render, legenda e montagem. Acompanhe na sessão do vídeo.`,
+  };
+}
+
+export async function selectTake(dir: string, line: string, version: string): Promise<Result> {
+  if (!LINE_ID.test(line) || !lineExists(dir, line)) return { ok: false, error: `a fala ${line} não existe` };
+  if (!VERSION.test(version)) return { ok: false, error: `versão inválida: ${version}` };
+  if (voiceTicketOf(dir))
+    return { ok: false, error: "a voz deste vídeo está sendo gerada agora: escolha quando ela terminar" };
+  const pause = pauseAfterVoice(dir, [line]);
+  const r = await run([PYTHON, OMNIVIDEO, "voice", dir, "--use", line, version], { OMNIVIDEO_ORIGIN: "studio" });
+  return r.code === 0
+    ? { ok: true, output: `${line}: versão escolhida; ${pauseNotice(pause)}` }
+    : { ok: false, error: (r.stderr || r.stdout).trim() };
+}
+
+/* the pause has just stopped the session: the process takes a moment to exit, and only
+   then does it accept a new message */
+async function waitAgentStopped(slug: string) {
+  for (let i = 0; i < 25 && latestSessionFor("video", slug)?.state === "running"; i++) await Bun.sleep(200);
+}
+
+/* "Seguir com estas vozes": lifts the pause and asks the video's Claude for what comes after
+   the voice, without touching any voice. With a voice still generating, waits for it to end. */
+export async function proceedWithVoices(dir: string, slug: string): Promise<Result> {
+  const pause = readPause(dir);
+  if (!pause) return { ok: false, error: "o vídeo não está pausado" };
+  if (voiceTicketOf(dir))
+    return { ok: false, error: "ainda há voz sendo gerada para este vídeo: siga quando ela terminar" };
+  await waitAgentStopped(slug);
+  rmSync(join(dir, PAUSE_FILE), { force: true });
+  const changed = pause.lines.includes("all") ? "todas as falas" : `as falas ${pause.lines.join(", ")}`;
+  const removed = pause.removed ?? [];
+  const message = [
+    ...(pause.lines.length
+      ? [`Troquei vozes pela tela (${changed}) e terminei: as falas agora são as que eu escolhi.`]
+      : []),
+    ...(removed.length
+      ? [
+          `Tirei pela tela da narração ${removed.length > 1 ? "as falas" : "a fala"} ${removed.join(", ")}: ${removed.length > 1 ? "saíram" : "saiu"} do scenes.json, e a leitura foi para history/voice/.`,
+          ...removedLinesRequest(readJson<any>(join(dir, "scenes.json")), removed),
+        ]
+      : []),
+    `Siga o vídeo pelo \`${PYTHON} tools/omnivideo.py status videos/${slug}\`: tempo, render, legenda e montagem, o que ele pedir.`,
+    "Não gere, não refaça e não troque nenhuma voz, nem para unificar o provider: fala com provider_pinned é escolha minha.",
+  ].join("\n");
+  const r = chatWith("video", slug, message);
+  if (!r.ok) {
+    /* without Claude the pause comes back: otherwise nothing holds the video and nobody redoes the render */
+    writeFileSync(join(dir, PAUSE_FILE), JSON.stringify(pause, null, 2) + "\n");
+    return { ok: false, error: `não deu para retomar o agente: ${r.error}` };
+  }
+  return { ok: true, output: "seguindo com estas vozes: o agente refaz tempo, render, legenda e montagem" };
+}

package/studio/runner/runner.ts

@@ -0,0 +1,244 @@
+/* The runner: this studio, reached from the hosted one (cloud/studio). It opens a WebSocket to the
+   cloud's RunnerHub and answers each request that arrives on it with the same Hono app the local
+   server uses, so every route, check and tool call is the one that runs at 127.0.0.1. Protocol in
+   tools/lib/channel.mjs; the plan in docs/specs/phase-1-split-api.md.
+
+   Locally `Bun.serve` answers Range for a Bun.file by itself; `app.fetch` doesn't, so the media paths
+   get their 206 here, from a slice of the file's Blob (never read whole). */
+
+import { hostname } from "node:os";
+import { PROTOCOL, Peer, REPLACED, REVOKED, UPGRADE } from "../../tools/lib/channel.mjs";
+
+/* the file routes of api/app.ts (API_PREFIXES) a player may ask a range of */
+const MEDIA_PREFIXES = [
+  "/media/",
+  "/ref/",
+  "/kit/",
+  "/sound-draft/",
+  "/docs/",
+  "/api/voice-sample/",
+  "/api/voice-original/",
+];
+const PING_MS = 30_000;
+const DEAD_MS = 75_000;
+/* without a key (not paired, or disconnected at /runner): how often to look for one in .env */
+const KEY_CHECK_MS = 30_000;
+/* a refused key pairs again by itself at most this often (the approval page opens on this Mac) */
+const PAIR_EVERY_MS = 60 * 60_000;
+
+export type RunnerOptions = {
+  /** the hosted studio, https://… */
+  url: string;
+  /** the Mac's credential, read on every attempt: the OAuth access token of `node tools/omni.mjs login`
+   *  (refreshed as needed) or the Phase 1 key (OMNIVIDEO_RUNNER_TOKEN, from `node tools/runner.mjs login`)
+   *  so a fresh login connects without restarting the studio */
+  token: () => string | Promise<string>;
+  /** the local server's port: the requests are rewritten to it, so `localOnly` admits them */
+  port: number;
+  handle: (request: Request) => Response | Promise<Response>;
+  log?: (line: string) => void;
+  /** whether the cloud still takes this key: false only when it says so (tools/lib/pairing.mjs checkKey) */
+  checkKey?: (token: string) => Promise<{ valid: boolean | null }>;
+  /** pairs this Mac again (opens the approval page, waits, saves the new key): the key, or null. Called when
+   *  the cloud refuses the key, never after a "Desconectar", which is the user's own decision */
+  pair?: () => Promise<string | null>;
+};
+
+/** Range on a media response: 206 from a Blob slice, 416 out of bounds; the rest as it is. */
+export async function withRange(request: Request, res: Response): Promise<Response> {
+  const path = new URL(request.url).pathname;
+  if (!MEDIA_PREFIXES.some(p => path.startsWith(p)) || res.status !== 200 || !res.body) return res;
+  const blob = await res.blob();
+  const headers = new Headers(res.headers);
+  headers.set("accept-ranges", "bytes");
+  if (blob.type && !headers.has("content-type")) headers.set("content-type", blob.type);
+  const range = /^bytes=(\d*)-(\d*)$/.exec(request.headers.get("range")?.trim() ?? "");
+  if (!range || (range[1] === "" && range[2] === "")) {
+    headers.set("content-length", String(blob.size));
+    return new Response(blob, { status: 200, headers });
+  }
+  const size = blob.size;
+  let start: number;
+  let end: number;
+  if (range[1] === "") {
+    start = Math.max(0, size - Number(range[2]));
+    end = size - 1;
+  } else {
+    start = Number(range[1]);
+    end = range[2] === "" ? size - 1 : Math.min(Number(range[2]), size - 1);
+  }
+  if (start >= size || start > end)
+    return new Response(null, { status: 416, headers: { "content-range": `bytes */${size}` } });
+  headers.set("content-range", `bytes ${start}-${end}/${size}`);
+  headers.set("content-length", String(end - start + 1));
+  return new Response(blob.slice(start, end + 1), { status: 206, headers });
+}
+
+/** A request from the channel, as the local server would have received it. */
+export function asLocal(request: Request, port: number): Request {
+  const u = new URL(request.url);
+  const headers = new Headers(request.headers);
+  headers.set("host", `127.0.0.1:${port}`);
+  /* the Worker already checked the browser's Origin against its own host */
+  headers.delete("origin");
+  /* it came through the hosted studio: the admin panel reads who sent it (x-ov-user, from the hub) */
+  headers.set("x-ov-via", "cloud");
+  return new Request(`http://127.0.0.1:${port}${u.pathname}${u.search}`, {
+    /* HEAD goes in as GET, as studio.ts does; the channel sends no body back for a HEAD */
+    method: request.method === "HEAD" ? "GET" : request.method,
+    headers,
+    body: request.body,
+    signal: request.signal,
+    // @ts-expect-error Bun needs it for a streaming request body
+    duplex: "half",
+  });
+}
+
+/** Connects and stays connected (backoff 1 s doubling to 60 s, with jitter). */
+export function startRunner(o: RunnerOptions) {
+  const log = o.log ?? ((line: string) => console.log(line));
+  const target = `${o.url.replace(/^http/, "ws")}/runner/connect`;
+  let delay = 1000;
+  let stopped = false;
+  let warned = false;
+  let socket: WebSocket | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let revoked = "";
+  let hinted = false;
+  let pairing = false;
+  let pairedAt = 0;
+
+  const serve = async (request: Request) => withRange(request, await o.handle(asLocal(request, o.port)));
+
+  const connect = async () => {
+    /* an unreachable studio while refreshing says nothing about the login: try again later */
+    const token = await Promise.resolve(o.token()).catch(() => "");
+    if (!token || token === revoked) {
+      if (!hinted) log("aviso: este Mac não está pareado com o studio hospedado: node tools/runner.mjs login");
+      hinted = true;
+      timer = setTimeout(connect, KEY_CHECK_MS);
+      return;
+    }
+    hinted = false;
+    const ws = new WebSocket(target, {
+      headers: {
+        authorization: `Bearer ${token}`,
+        "x-ov-protocol": String(PROTOCOL),
+        /* the hub says which Mac it refused, on the hosted page */
+        "x-ov-runner-host": encodeURIComponent(hostname().replace(/\.local$/, "")),
+      },
+    } as unknown as string[]);
+    ws.binaryType = "arraybuffer";
+    socket = ws;
+    let peer: Peer | null = null;
+    let lastPong = Date.now();
+    let ping: ReturnType<typeof setInterval> | null = null;
+
+    ws.onopen = () => {
+      delay = 1000;
+      warned = false;
+      peer = new Peer({
+        send: (f: Uint8Array) => ws.send(f as Uint8Array<ArrayBuffer>),
+        onRequest: serve,
+        /* what the uplink still holds: media waits on it, so Omni's lines never queue behind a video */
+        backlog: () => ws.bufferedAmount,
+      });
+      log(`cloud: studio hospedado conectado (${o.url})`);
+      /* "ping" is answered by the hub's auto-response without waking it; no pong for a while = dead */
+      ping = setInterval(() => {
+        if (Date.now() - lastPong > DEAD_MS) return ws.close(4001, "sem resposta da cloud");
+        ws.send("ping");
+      }, PING_MS);
+    };
+    ws.onmessage = e => {
+      if (typeof e.data === "string") {
+        lastPong = Date.now();
+        return;
+      }
+      peer?.receive(e.data as ArrayBuffer);
+    };
+    ws.onclose = e => {
+      if (ping) clearInterval(ping);
+      const was = !!peer;
+      peer?.close("o studio hospedado desconectou");
+      peer = null;
+      if (stopped) return;
+      /* another studio took the hosted one over: retrying would only knock it off in turn */
+      if (e.code === REPLACED) {
+        stopped = true;
+        return log("aviso: outro studio assumiu o studio hospedado; este parou de atender por ele");
+      }
+      /* the key was deleted at /runner: wait for a new pairing instead of knocking with the old key */
+      if (e.code === REVOKED) {
+        revoked = token;
+        log("aviso: este Mac foi desconectado do studio hospedado; para voltar: node tools/runner.mjs login");
+        hinted = true;
+        timer = setTimeout(connect, KEY_CHECK_MS);
+        return;
+      }
+      /* the hub and this Mac speak different protocols: say which side is old, and look again in a minute
+         (the studio may be redeployed, or this Mac updated, without a restart) */
+      if (e.code === UPGRADE) {
+        if (!warned) log(`aviso: este Mac e o studio hospedado não se entendem (${e.reason}); tento de novo em 1 min`);
+        warned = true;
+        timer = setTimeout(connect, 60_000);
+        return;
+      }
+      if (was || !warned) {
+        log(`cloud: sem conexão com o studio hospedado (${e.code}${e.reason ? ` ${e.reason}` : ""}); tentando de novo`);
+        warned = true;
+      }
+      const retry = () => {
+        timer = setTimeout(connect, delay * (0.75 + Math.random() / 2));
+        delay = Math.min(delay * 2, 60_000);
+      };
+      /* never opened: the cloud may have refused the key itself (not an unreachable cloud) */
+      if (!was && o.checkKey && o.pair) void repair(token).then(handled => handled || retry());
+      else retry();
+    };
+    ws.onerror = () => {
+      /* onclose follows */
+    };
+  };
+  /* The key was refused (the login was redone, the key went missing in the cloud…): pair again, which opens
+     the approval page on this Mac, and connect with the new key. True when it took over the retry. */
+  const repair = async (token: string): Promise<boolean> => {
+    if (stopped || pairing) return true;
+    const k = await o.checkKey!(token).catch(() => ({ valid: null }));
+    if (k.valid !== false) return false;
+    revoked = token;
+    if (Date.now() - pairedAt < PAIR_EVERY_MS) {
+      timer = setTimeout(connect, KEY_CHECK_MS);
+      return true;
+    }
+    pairing = true;
+    pairedAt = Date.now();
+    log(
+      "aviso: o studio hospedado recusou a chave deste Mac; abri a página de aprovação no navegador: aprove para reconectar",
+    );
+    const key = await o.pair!().catch(e => {
+      log(
+        `aviso: o pareamento não terminou (${(e as Error).message}); de novo daqui a 1 h, ou: node tools/runner.mjs login`,
+      );
+      return null;
+    });
+    pairing = false;
+    if (stopped) return true;
+    if (key) {
+      log("cloud: Mac pareado de novo");
+      delay = 1000;
+      hinted = false;
+      void connect();
+    } else timer = setTimeout(connect, KEY_CHECK_MS);
+    return true;
+  };
+
+  void connect();
+  return {
+    stop() {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+      socket?.close(1000, "runner parou");
+    },
+  };
+}

package/studio/shared/omni-actions.ts

@@ -0,0 +1,68 @@
+/* Omni's staged actions (api/services/agent-tools.ts) as the screen follows them: the studio screen
+   where each one's result shows, which the page opens when the card appears (or, for something that
+   doesn't exist yet, once it is confirmed), and which ones leave a Claude working for minutes. One
+   catalog for the server, which hands the screen to the model, and for the browser, which opens it. */
+
+import type { NavigateArgs } from "./omni-screens";
+
+export type ActionKind =
+  | "change"
+  | "create"
+  | "thumbnail"
+  | "publish"
+  | "schedule"
+  | "approval"
+  | "reference"
+  | "new_reference"
+  | "choose_thumbnail"
+  | "analysis"
+  | "omnichat"
+  | "omnichat_send";
+
+/* the screen of an action's result. `slug` is the video's slug, or the reference's name (kind
+   reference); null: no screen to open */
+export function actionScreen(
+  kind: ActionKind,
+  slug: string | null,
+  payload: Record<string, unknown>,
+): NavigateArgs | null {
+  const p = payload as Record<string, any>;
+  switch (kind) {
+    case "thumbnail":
+    case "choose_thumbnail":
+      return slug ? { screen: "video", slug, stage: "publish", tab: "thumbnail" } : null;
+    case "publish":
+    case "schedule":
+      if (!slug) return null;
+      return p.content === "carousel"
+        ? { screen: "video", slug, stage: "carousel-publish", tab: "post" }
+        : { screen: "video", slug, stage: "publish", tab: "info" };
+    case "omnichat":
+    case "omnichat_send":
+      return slug ? { screen: "omnichat_rule", slug, content: p.content === "carousel" ? "carousel" : "video" } : null;
+    case "approval":
+      return slug ? { screen: "video", slug, stage: p.round === "scenes" ? "motion_script" : "script" } : null;
+    case "change":
+      if (!slug) return null;
+      return p.where === "edit" ? { screen: "video", slug, stage: "render", tab: "agent" } : { screen: "video", slug };
+    case "create":
+      return slug ? { screen: "video", slug } : null;
+    case "reference":
+      return slug ? { screen: "style", name: slug } : null;
+    case "new_reference":
+      return typeof p.name === "string" ? { screen: "style", name: p.name } : null;
+    case "analysis":
+      return slug ? { screen: "video_metrics", slug } : { screen: "analytics" };
+  }
+}
+
+/* a new content or reference has no screen until it exists: those open once confirmed, the rest when
+   the card appears */
+export const opensOnConfirm = (kind: ActionKind) => kind === "create" || kind === "new_reference";
+
+/* a confirmed action whose work takes minutes: Omni offers to wait instead of filling the silence */
+const ASYNC_KINDS = new Set<string>(["change", "create", "thumbnail", "reference", "approval"]);
+export const waitHint = (kind: string) =>
+  ASYNC_KINDS.has(kind)
+    ? " Isso deixa o Claude trabalhando por alguns minutos: diga numa frase que vai esperar e chame wait_for_work."
+    : "";