@crievo/omni 0.1.7 → 0.1.9

package/omnivideo.config.example.json

@@ -136,6 +136,7 @@
       ]
     },
     "kit": "kit/sfx",
+    "default_kit": "motion-ui",
     "roles": {
       "click": {
         "db": -4
@@ -293,6 +294,7 @@
     "omnichat": false,
     "metrics": false,
     "schedule": false,
+    "user": false,
     "studio": false,
     "studio_url": ""
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crievo/omni",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "OmniVideo no seu computador: o CLI omni, o studio local e as ferramentas do pipeline.",
   "type": "module",
   "bin": {

package/reference/cloud.md

@@ -39,7 +39,7 @@ and the studio talk to the Worker with `OMNICHAT_CLOUD_SECRET` (the Worker's `SY
   back if it stops, log in `.runner/studio.log`; `service restart` after a `git pull`). Setup:
   `node cloud/studio/setup-auth.mjs` (tables and secrets), then `npx wrangler deploy` in `cloud/studio`.
   Every write that goes through to the Mac is logged (email, method, path, status; the last 2000, at
-  `<studio>/runner/audit`) and limited to 120 a minute per user (429 beyond it); a runner and a hub on
+  Configurações → Agente de IA, from `<studio>/session/audit`) and limited to 120 a minute per user (429 beyond it); a runner and a hub on
   different protocol numbers refuse each other and say which side is old.
   Protocol in `tools/lib/channel.mjs`, plan in `docs/specs/phase-1-split-api.md`.
 - **Each job has an off switch in the database** (`settings`: `active`, `metrics_active`,
@@ -55,6 +55,20 @@ and the studio talk to the Worker with `OMNICHAT_CLOUD_SECRET` (the Worker's `SY
 
 Turning back: the flag to `false` and the push again (the cloud stops), and the local agent on.
 
+## The per-user cloud (Phase 3, in progress)
+
+The jobs above are moving from the shared `omnichat` Worker into one Durable Object per user, `UserCloud` in the studio
+Worker (`cloud/studio/src/cloud-*.mjs`), with their own config, secrets, webhook (`/hook/<cloudId>`), media
+(`u/<cloudId>/` in R2) and one alarm in place of the crons and the KV gate. Step 2 (the jobs inside the object) is built and
+tested but not deployed or used by a machine yet; the `omnichat` Worker above still does the real work until steps 3–4.
+Routes, flags and what differs from the sketch: `docs/specs/phase-3-per-user-cloud.md`, "Step 2, as built".
+
+On the machine, `cloud.user: true` (with `cloud.studio_url`, signed in with the Omni login) points the omnichat, the
+Instagram account and the metrics at that cloud instead of the Worker; publishing (the schedule, the media published
+now, the YouTube/TikTok credentials) stays on the Worker until the last step. Off by default: turning it on points the
+CLIs at an empty cloud, so see "Step 3, as built so far" in the spec for the order (push first, and the Worker stops
+answering before the new cloud starts).
+
 ## Free plans and their limits
 
 - **Workers Free:** 10 ms of CPU and 50 subrequests per run. That is why a cloud pass sends at most 5 DMs

package/reference/learnings.md

@@ -814,3 +814,10 @@ these voices).
 - **Symptom:** none yet; found reading the queue for a Windows port.
 - **Cause:** on Windows, Python's `os.kill(pid, sig)` treats `sig == 0` as `CTRL_C_EVENT` and sends it to the process group of `pid`; any other number is a `TerminateProcess`. The Node `process.kill(pid, 0)` is a real probe on both systems.
 - **Fixed:** `tools/job_queue.py` asks the kernel (`OpenProcess` + `GetExitCodeProcess`, `STILL_ACTIVE`) on Windows and keeps `os.kill` plus the `ps` zombie check elsewhere. Also on Windows: `select()` works on sockets only (the guardian reads the Node pipe in a thread), an atomic replace fails while a reader has the file open (retry), and a text file is written in the code page unless `encoding="utf-8"` says otherwise.
+
+## A turn's `total_cost_usd` is the session's running total, not the turn's (18/10/2026)
+
+- **Symptom:** the studio's session list showed US$ 220,93 for the Grok video, whose last turn closed at US$ 53,79. Measuring cost by hand from the transcripts had given a different number each time.
+- **Cause:** `claude -p --resume` keeps adding to the conversation's totals. The `result` of turn N carries `total_cost_usd`, `modelUsage[].costUSD` and `duration_api_ms` since the conversation began (same `session_id`, only growing: 4,01 → 10,07 → 22,98 → … → 53,79). Summing the turns' costs counts the early turns again and again. The per-message `usage` in the stream-json is no substitute: it is a partial reading, with the output tokens undercounted (about 10 to 30 % under the real cost).
+- **Fixed:** `tools/lib/cost.mjs` takes a turn's cost as the difference to the previous `result` of the same `session_id`, and uses the messages' `usage` only to split that cost between forks (scaled per model to what the `result` says). A turn that never closed (running, interrupted) is an estimate, and the next `result` gives that estimate back so the session still adds up to its last total. `summarizeSession` counts each conversation once, by its last total. Rule: to measure what an agent spent, run `node tools/cost.mjs`; do not add up `result` costs by hand, and count messages by `message.id`, never by transcript line.
+

package/reference/scenes-contract.md

@@ -45,7 +45,7 @@ the others only read it. A full example is in `templates/scenes.example.json`.
 | `element` | 3 | name of what enters; becomes the CSS variable `--b-<element>` |
 | `t` | 3 | provisional time in seconds, used until a voice exists |
 | `enters_with` | 4 | reference to the line: `c01f2`, `c01f2:end`, `c01f2:palavra`, `c01f2:palavra#2`, with optional `+0.3`/`-0.3`. The word is the spoken (PT) word; `:fim` is still accepted as a legacy alias of `:end` |
-| `sound` | 3, optional | effect on the beat: a file name in the global kit (`kit/sfx/kit.json`) or in `<video>/sfx/`, captured from Epidemic and registered in `sfx/sources.json` (`"clique-seco.mp3"`), an object with adjustments, or a list of them (layers at the same instant). Fields below |
+| `sound` | 3, optional | effect on the beat: a file name in a sound kit (`kit/sfx/<kit>/`, `"clique-seco.mp3"`) or in `<video>/sfx/` (captured from Epidemic or sent by the user, registered in `sfx/sources.json`), an object with adjustments, or a list of them (layers at the same instant). Fields below |
 
 `tools/timing.mjs` → `beatTime(scene, beat)` resolves it: `enters_with` if
 present, otherwise `t`.
@@ -54,7 +54,8 @@ present, otherwise `t`.
 
 | field | default | what it is |
 |---|---|---|
-| `name` | required | file in the video's `sfx/` or in the global kit (`kit/sfx/`); the video's one wins. From the kit, the role's `db` is added (`sound.roles`) |
+| `name` | required | file in the video's `sfx/` or in a kit; the video's one wins. From a kit, the role's `db` is added (`sound.roles`) |
+| `kit` | the default kit (`sound.default_kit`, `motion-ui`) | which kit the file comes from when it is not in the video's `sfx/`: `"epidemic-sounds"` for the Epidemic effects. A sound never falls back to another kit: a name only in another kit fails and says which one to name |
 | `anchor` | `"peak"` | which point of the effect lands on the instant: `"peak"` (the loudest sample) or `"start"` |
 | `offset` | 0 | seconds after the instant (negative: before) |
 | `db` | 0 | adjustment over the default level: `sound.level_db` below the voice's integrated loudness |

package/reference/studio.md

@@ -589,11 +589,12 @@ comes, that it be the studio's own.
 | `GET /api/videos/<slug>/captions/page` | the video's `captions.html` (`?preview=1` marks the safe area and accepts `postMessage({ position, t })`) |
 | `GET /api/videos/<slug>/captions/frame?t=` | JPEG of the motion at second `t` of the video, from the scene's MP4 |
 | `POST /api/videos/<slug>/captions/position` | `{ scope: "video" \| "scene" \| "caption", target?, value }` → `captions` in `scenes.json`; `value: null` removes a scene's or caption's adjustment |
-| `GET /api/videos/<slug>/sound` | sound timeline: total, scenes, lines (video time), sound places (each beat with its instant and each scene change, with the sounds), the bed, the catalog (kit by role and the video's `sfx/`, measured) and the export's base MP4 |
+| `GET /api/videos/<slug>/sound` | sound timeline: total, scenes, lines (video time), sound places (each beat with its instant and each scene change, with the sounds), the bed, the catalog (the kits by role, each effect named `kit/name.mp3`, and the video's `sfx/`, measured) and the export's base MP4 |
 | `POST /api/videos/<slug>/sound/plan` | `{ places, bed }` (draft) → the `sound.mjs` plan with the URL of each finished WAV under `/sound-draft/<slug>/…`; nothing is written to the video |
 | `POST /api/videos/<slug>/sound` | `{ places, bed }` → `sound` on the beats, `transition.sound` and `bed` in `scenes.json` (validated; defaults are dropped) |
 | `POST /api/videos/<slug>/sound/reassemble` | runs `assemble.mjs` (waits for its turn in the queue) |
-| `GET /kit/<name>` | MP3 from the global kit (`kit/sfx/`), for the waveform |
+| `GET /kit/<kit>%2F<name>` | MP3 from a sound kit (`kit/sfx/<kit>/`), by the catalog's name `kit/name.mp3`, for the waveform |
+| `GET /api/cost` | `tools/lib/cost.mjs`: what the Claude sessions spent, by video, stage, fork, model and day (`?days=N`); reads `.sessions/`, cache in `.cost/` |
 | `GET /api/usage` | `tools/usage.py summary --json`: Fish balance, Cartesia quota, usage per video and latest generations (only reads the local log) |
 | `POST /api/usage/refresh` | the same with `--live`: asks the platforms now and writes the reading to `.usage/` |
 | `GET /api/analytics` | `tools/analysis.mjs context` (account, medians at the current reading and at the 24 h and 72 h milestones, also per thousand views, the channel's hour-by-hour `progression` and the `publications` in it, the playbook's `before` range, each Reel with metrics, strategy and hook, the agent) plus the text of the latest channel analysis |

package/studio/api/app.ts

@@ -28,6 +28,7 @@ import { onboarding } from "./routes/onboarding";
 import { publish } from "./routes/publish";
 import { queue } from "./routes/queue";
 import { references } from "./routes/references";
+import { me } from "./routes/me";
 import { runner } from "./routes/runner";
 import { schedule } from "./routes/schedule";
 import { services } from "./routes/services";
@@ -36,6 +37,7 @@ import { settings } from "./routes/settings";
 import { sound, SOUND_UPLOAD_PATH } from "./routes/sound";
 import { thumbnail } from "./routes/thumbnail";
 import { usage } from "./routes/usage";
+import { cost } from "./routes/cost";
 import { videos } from "./routes/videos";
 import { voices } from "./routes/voices";
 
@@ -63,8 +65,10 @@ export function createApp({ port }: AppOptions) {
     .route("/", references)
     .route("/", queue)
     .route("/", runner)
+    .route("/", me)
     .route("/", services)
     .route("/", usage)
+    .route("/", cost)
     .route("/", analytics)
     .route("/", settings)
     .route("/", clone)

package/studio/api/routes/cost.ts

@@ -0,0 +1,13 @@
+/* Agent cost (settings Uso e custo): what the Claude sessions spent, by video, stage and model. */
+
+import { router } from "../lib/hono";
+import { shaped } from "../lib/result";
+import { query } from "../lib/validate";
+import { getCost } from "../services/cost";
+import { costQuery } from "../../shared/schemas/cost";
+import type { AgentCost } from "../../shared/types/api";
+
+export const cost = router().get("/cost", query(costQuery), async c => {
+  const days = Number(c.req.valid("query").days) || null;
+  return c.json(shaped<AgentCost>(await getCost(days)));
+});

package/studio/api/routes/me.ts

@@ -0,0 +1,8 @@
+/* Who is using the studio (services/me.ts), for the menu's user card at 127.0.0.1, and its sign-out. */
+
+import { router } from "../lib/hono";
+import { getMe, signOutOmni } from "../services/me";
+
+export const me = router()
+  .get("/me", async c => c.json({ me: await getMe() }))
+  .post("/me/logout", async c => c.json(await signOutOmni()));

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

@@ -27,6 +27,7 @@ O que você faz, e só isso:
 - Olhar a composição e o resultado (inspect_content): o quadro de uma cena (ou o do segundo at), a folha de contato dela (o movimento), o corte que a abre, o wireframe, várias cenas lado a lado, o vídeo exportado e os slides do carrossel. Para "essa cena está boa?", pergunte algo objetivo (o elemento principal aparece? o texto é legível?).
 - Mostrar as coisas abrindo a tela delas, não no seu painel: "mostra as thumbs" é navigate com stage publish e tab thumbnail; "o Omnichat desse vídeo", navigate com screen omnichat_rule e o slug (content carousel para o do carrossel); o vídeo exportado, stage publish; o carrossel, stage carousel-publish; os números, video_metrics. Um pedido (thumbnail, publicação, Omnichat, aprovação, alteração) já abre sozinho a tela onde o resultado aparece: não chame navigate para ela de novo. O card no seu painel (show_card) é só quando o usuário pedir para ver ali, sem sair da tela onde está.
 - No editor de um vídeo já montado: tocar e pausar (control_editor) e adicionar uma música ou um efeito da Epidemic Sound (add_epidemic_sound, com a busca em inglês, como "calm piano"), só quando o usuário pedir. Avise que o Claude do editor baixa a faixa em um ou dois minutos e que ela entra nos sons do vídeo.
+- Os efeitos vêm de kits (pastas de sons). O padrão é o kit motion-ui (sons de interface sintetizados, do bencho.dev): quando o usuário pede um som sem dizer de onde, é desse kit. O kit epidemic-sounds tem os efeitos capturados da Epidemic. Quando o usuário pedir para editar um som, diga de qual kit ele é, e não troque o kit de um som sem pedido: o Claude do editor é quem muda o som, então passe o kit no pedido. add_epidemic_sound baixa só para este vídeo, não para um kit.
 - A agenda (get_schedule): o que está agendado e o que foi publicado em cada dia, com a hora, as plataformas e o Omnichat de cada um. Para "o que sai amanhã", "o que tem essa semana", "o que publiquei ontem".
 - O Omnichat de um conteúdo publicado ou agendado (omnichat_status, set_omnichat): você configura sozinha, sem card. Leia a regra (omnichat_status), decida e grave com set_omnichat: palavras, link, o texto da DM, as respostas públicas e as fases da DM (botão; só para quem segue, com a mensagem de quem não segue e o "Receber sem seguir"; o link num botão). O Omnichat de um conteúdo se configura sempre na tela dele, /omnichat/video/<slug> (screen omnichat_rule), nunca na etapa Publicar: ela abre sozinha com o set_omnichat e mostra a regra mudando. Depois diga numa frase o que gravou e, se faltar algo para ligar (missing_to_enable), o que falta. Ligar as respostas automáticas responde em nome da conta: só quando o usuário pedir para ligar, com essas palavras; desligar, quando ele pedir.
 - Quando o pedido depende de um link ou de um texto que o usuário precisa colar (um vídeo para virar estilo visual, uma página, um roteiro pronto), chame ask_in_chat e diga numa frase o que colar no chat. O chat abre com o campo pronto; se o usuário responder por voz que não quer ou mudar de assunto, ele fecha sozinho. Não peça para ele ditar um link.

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

@@ -853,7 +853,7 @@ const SCHEDULE_STATE: Record<string, string> = {
   scheduled: "agendado",
   publishing: "publicando agora",
   failed: "falhou",
-  missed: "perdido (o Mac estava desligado)",
+  missed: "perdido (a máquina estava desligada)",
 };
 
 export async function toolSchedule(from?: string, to?: string, now = new Date()): Promise<ToolOutput> {
@@ -1858,7 +1858,7 @@ async function toolOmnichatStatus(slug?: string, content?: "video" | "carousel")
       account: st.account?.ready ? { username: st.account.username ?? null } : { problem: st.account?.reason ?? null },
       comments_permission: st.comments?.ready ?? null,
       /* who answers the comments: the cloud Worker, or this Mac's launchd agent */
-      answered_by: st.agent?.cloud?.ready ? "nuvem" : st.agent?.loaded ? "este Mac" : "ninguém (agente parado)",
+      answered_by: st.agent?.cloud?.ready ? "nuvem" : st.agent?.loaded ? "esta máquina" : "ninguém (agente parado)",
       pause: st.pause,
       rules: (st.rules ?? []).map((r: any) => ({
         content: r.type,

package/studio/api/services/cost.ts

@@ -0,0 +1,22 @@
+/* What the agents spent on the videos. The accounting lives in tools/lib/cost.mjs, which
+   tools/cost.mjs (the terminal) also uses; the studio only shows what it returns.
+   A finished turn is cached on disk, but the open ones are read again, so the answer is kept for
+   a few seconds: the UI reloads on every queue change. */
+
+import { readTurns, summarize } from "../../../tools/lib/cost.mjs";
+
+const cached = new Map<string, { at: number; data: Promise<unknown> }>();
+
+export function getCost(days: number | null) {
+  const key = String(days ?? "all");
+  const hit = cached.get(key);
+  if (hit && Date.now() - hit.at < 5000) return hit.data;
+  const data = readTurns({ since: days ? Date.now() - days * 86_400_000 : null }).then(rows => ({
+    days,
+    ...summarize(rows),
+  }));
+  cached.set(key, { at: Date.now(), data });
+  /* a failed reading is not kept */
+  data.catch(() => cached.delete(key));
+  return data;
+}

package/studio/api/services/me.ts

@@ -0,0 +1,67 @@
+/* Who is using the studio, for the menu's user card (GET /api/me). The hosted page doesn't ask this: the Worker
+   answers /session/me from the signed-in session, even while this computer is away. Here, at 127.0.0.1, it is
+   the account signed in to Omni on this computer (the plugin's login: the Worker's /account), else the Claude
+   Code account that runs the agent (its name and email, read from its own files), which also fills in a name the
+   Omni account doesn't carry yet. Without either, nobody:
+   the card hides. Cached a minute: the menu asks on every page and the Worker needn't hear that often. */
+
+import { accountsOf, loginOf } from "../../../tools/lib/agents.mjs";
+import { accessToken, logout, readTokens } from "../../../tools/lib/oauth-client.mjs";
+import { cloudSettings } from "../../../tools/platforms.mjs";
+import type { Me } from "../../shared/types/api";
+import { readConfig } from "./settings";
+
+const TTL_MS = 60_000;
+let cached: { at: number; me: Me | null } | null = null;
+
+/* the Omni account of this computer: its login's token trades for the account at the Worker */
+async function omniAccount(): Promise<Me | null> {
+  const url = cloudSettings().studio.url;
+  if (!url) return null;
+  try {
+    const token = await accessToken(url);
+    if (!token) return null;
+    const r = await fetch(`${url}/account`, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(4000),
+    });
+    if (!r.ok) return null;
+    const a = (await r.json()) as { email?: string | null; name?: string | null; image?: string | null };
+    return a.email ? { name: a.name ?? null, email: a.email, image: a.image ?? null, source: "omni" } : null;
+  } catch {
+    return null;
+  }
+}
+
+/* the Claude Code account the agent runs on */
+function claudeAccount(): Me | null {
+  for (const a of accountsOf(readConfig() ?? {}) as { provider: string }[]) {
+    if (a.provider !== "claude") continue;
+    const login = loginOf(a) as { email: string | null; name?: string | null } | null;
+    if (login?.email) return { name: login.name ?? null, email: login.email, image: null, source: "claude" };
+  }
+  return null;
+}
+
+export async function getMe(now = Date.now()): Promise<Me | null> {
+  if (cached && now - cached.at < TTL_MS) return cached.me;
+  const claude = claudeAccount();
+  const omni = await omniAccount();
+  /* the Worker may not know the name yet: the Claude Code account of the same email does */
+  const me = omni ? { ...omni, name: omni.name ?? (claude?.email === omni.email ? claude.name : null) } : claude;
+  cached = { at: now, me };
+  return me;
+}
+
+/* Sair da conta Omni deste computador: the same as `omni logout`. The Worker is told to end this computer's login
+   and the tokens here are forgotten; the card then falls back to the Claude Code account, or hides. */
+export async function signOutOmni(): Promise<{ ok: boolean; output?: string; error?: string }> {
+  const url = cloudSettings().studio.url;
+  if (!url || !readTokens(url)) return { ok: false, error: "Este computador não está logado na conta Omni." };
+  const confirmed = await logout(url);
+  cached = null;
+  return {
+    ok: true,
+    output: confirmed ? "Saiu da conta Omni." : "Saiu da conta Omni aqui; o studio hospedado não confirmou.",
+  };
+}

package/studio/api/services/sessions.ts

@@ -336,7 +336,13 @@ function stateOf(r: SessionRecord): { state: SessionState; result: TurnResult |
 export function summarizeSession(r: SessionRecord) {
   const { state, result, now } = stateOf(r);
   const t = r.turns.at(-1);
-  const costs = r.turns.map(x => turnInfo(r, x).result?.cost ?? 0);
+  /* a turn's `cost` is the conversation's running total (--resume keeps adding to it), so a
+     conversation counts once, by its last total; a handoff to another account is a new one */
+  const running = new Map<string, number>();
+  for (const x of r.turns) {
+    const cost = turnInfo(r, x).result?.cost;
+    if (cost != null) running.set(x.engine_id ?? r.id, Math.max(running.get(x.engine_id ?? r.id) ?? 0, cost));
+  }
   const account = t ? accountOfTurn(r, t) : null;
   let activity = Date.parse(r.created_at);
   try {
@@ -355,7 +361,7 @@ export function summarizeSession(r: SessionRecord) {
     turns: r.turns.length,
     turn: t ? { n: t.n, origin: t.origin, prompt: t.prompt, started_at: t.started_at, pid: t.pid, result } : null,
     now,
-    total_cost: +costs.reduce((a, b) => a + b, 0).toFixed(4),
+    total_cost: +[...running.values()].reduce((a, b) => a + b, 0).toFixed(4),
     agent: t ? { provider: providerOf(t), account: account?.id ?? null, label: account?.label ?? null } : null,
   };
 }

package/studio/api/services/sound.ts

@@ -18,7 +18,8 @@ import {
   sanitizeBed,
   sanitizeSpeed,
   finalClock,
-  kitDir,
+  kitDirOf,
+  kitNames,
 } from "../../../tools/sound.mjs";
 import { videoClips, lineClips, lineDuration } from "../../../tools/soundtrack.mjs";
 import { normalizeCuts } from "../../../tools/cuts.mjs";
@@ -28,7 +29,12 @@ import type { ApiResult } from "./sessions";
 type Result = { ok: true; output: string } | { ok: false; error: string };
 const DRAFT_DIR = join(ROOT, ".sound-draft");
 
-const normalizeSound = (s: any) => (typeof s === "string" ? { name: s } : { ...s });
+/* a sound from scenes.json: its kit's effect is shown by the ref "kit/name.mp3", as the catalog names it */
+const normalizeSound = (s: any) => {
+  const o = typeof s === "string" ? { name: s } : { ...s };
+  if (o.kit && typeof o.name === "string" && !o.name.includes("/")) o.name = `${o.kit}/${o.name}`;
+  return o;
+};
 const asList = (sound: any) => (sound == null ? [] : (Array.isArray(sound) ? sound : [sound]).map(normalizeSound));
 
 /* the export's base MP4 (without the speed), for the timeline picture, and the cuts it already has */
@@ -164,10 +170,15 @@ export function draftFile(slug: string, rest: string): string | null {
   return abs.startsWith(base + sep) && abs.endsWith(".wav") && existsSync(abs) ? abs : null;
 }
 
-/* a file from the global kit, for the waveform */
-export function kitFile(name: string): string | null {
-  const abs = resolve(kitDir, name);
-  return abs.startsWith(resolve(kitDir) + sep) && abs.endsWith(".mp3") && existsSync(abs) ? abs : null;
+/* a file of a kit, for the waveform: the ref "kit/name.mp3" (the catalog's name for a kit effect) */
+export function kitFile(ref: string): string | null {
+  const i = ref.indexOf("/");
+  const kit = i > 0 ? ref.slice(0, i) : "";
+  const name = i > 0 ? ref.slice(i + 1) : "";
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(kit) || !kitNames().includes(kit)) return null;
+  const dir = kitDirOf(kit);
+  const abs = resolve(dir, name);
+  return abs.startsWith(resolve(dir) + sep) && abs.endsWith(".mp3") && existsSync(abs) ? abs : null;
 }
 
 /* writes the draft to scenes.json: the sound of each beat, each transition, the bed and the cuts */

package/studio/runner/runner.ts

@@ -25,6 +25,9 @@ const DEAD_MS = 75_000;
 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;
+/* with no login (never entered, signed out, or disconnected at the studio) the approval page opens on this computer by
+   itself, at most this often: it asks for a click, and someone who closed it didn't want it every hour */
+const LOGIN_EVERY_MS = 6 * 60 * 60_000;
 
 export type RunnerOptions = {
   /** the hosted studio, https://… */
@@ -42,6 +45,18 @@ export type RunnerOptions = {
   /** 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>;
+  /** signs this computer in again: opens the approval page in the browser and waits for the user to approve
+   *  (tools/lib/oauth-client.mjs login). Called when there is no usable login, so nobody has to open a terminal or
+   *  Claude Code to get back in; the user only approves */
+  login?: () => Promise<void>;
+  /** the hub says this machine and the hosted studio speak different protocols (UPGRADE). Which side is old isn't
+   *  in the close reason, so whoever answers this looks (tools/lib/self-update.mjs: is there a newer version of
+   *  the CLI?) and updates this machine when it is the one behind. Called on every retry, a minute apart. */
+  onOutdated?: () => void | Promise<void>;
+  /** the waits, in ms; the tests shorten them */
+  keyCheckMs?: number;
+  loginEveryMs?: number;
+  protocolRetryMs?: number;
 };
 
 /** Range on a media response: 206 from a Blob slice, 416 out of bounds; the rest as it is. */
@@ -107,6 +122,10 @@ export function startRunner(o: RunnerOptions) {
   let hinted = false;
   let pairing = false;
   let pairedAt = 0;
+  const keyCheckMs = o.keyCheckMs ?? KEY_CHECK_MS;
+  const loginEveryMs = o.loginEveryMs ?? LOGIN_EVERY_MS;
+  let signingIn = false;
+  let signedInAt = 0;
 
   const serve = async (request: Request) => withRange(request, await o.handle(asLocal(request, o.port)));
 
@@ -114,9 +133,10 @@ export function startRunner(o: RunnerOptions) {
     /* 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: npx -y @crievo/omni login");
+      if (!hinted) log("aviso: esta máquina não está conectada ao studio hospedado");
       hinted = true;
-      timer = setTimeout(connect, KEY_CHECK_MS);
+      void signIn();
+      timer = setTimeout(connect, keyCheckMs);
       return;
     }
     hinted = false;
@@ -171,17 +191,20 @@ export function startRunner(o: RunnerOptions) {
       /* 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");
+        log("aviso: esta máquina foi desconectada do studio hospedado");
         hinted = true;
-        timer = setTimeout(connect, KEY_CHECK_MS);
+        /* the next look finds no login and opens the approval page (once): the user can approve or refuse it */
+        timer = setTimeout(connect, keyCheckMs);
         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`);
+        if (!warned)
+          log(`aviso: esta máquina e o studio hospedado não se entendem (${e.reason}); tento de novo em 1 min`);
         warned = true;
-        timer = setTimeout(connect, 60_000);
+        void Promise.resolve(o.onOutdated?.()).catch(() => {});
+        timer = setTimeout(connect, o.protocolRetryMs ?? 60_000);
         return;
       }
       if (was || !warned) {
@@ -200,6 +223,30 @@ export function startRunner(o: RunnerOptions) {
       /* onclose follows */
     };
   };
+  /* No usable login: opens the approval page on this computer and waits for the user to approve, then connects with
+     the login it stored. At most once in a while, and never twice at the same time. */
+  const signIn = async () => {
+    if (!o.login || stopped || signingIn) return;
+    if (signedInAt && Date.now() - signedInAt < loginEveryMs) return;
+    signingIn = true;
+    signedInAt = Date.now();
+    log("aviso: abri a página de aprovação no navegador desta máquina: aprove para reconectar");
+    try {
+      await o.login();
+      log("cloud: login refeito");
+      delay = 1000;
+      hinted = false;
+      revoked = "";
+      if (!stopped) {
+        if (timer) clearTimeout(timer);
+        void connect();
+      }
+    } catch (e) {
+      log(`aviso: o login não terminou (${(e as Error).message})`);
+    } finally {
+      signingIn = false;
+    }
+  };
   /* 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> => {
@@ -208,13 +255,13 @@ export function startRunner(o: RunnerOptions) {
     if (k.valid !== false) return false;
     revoked = token;
     if (Date.now() - pairedAt < PAIR_EVERY_MS) {
-      timer = setTimeout(connect, KEY_CHECK_MS);
+      timer = setTimeout(connect, keyCheckMs);
       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",
+      "aviso: o studio hospedado recusou a chave desta máquina; abri a página de aprovação no navegador: aprove para reconectar",
     );
     const key = await o.pair!().catch(e => {
       log(
@@ -225,11 +272,11 @@ export function startRunner(o: RunnerOptions) {
     pairing = false;
     if (stopped) return true;
     if (key) {
-      log("cloud: Mac pareado de novo");
+      log("cloud: máquina pareada de novo");
       delay = 1000;
       hinted = false;
       void connect();
-    } else timer = setTimeout(connect, KEY_CHECK_MS);
+    } else timer = setTimeout(connect, keyCheckMs);
     return true;
   };
 

package/studio/shared/omni-screens.ts

@@ -39,7 +39,7 @@ export const SCREENS: Record<ScreenId, { label: string; path: string }> = {
   /* 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" },
+  usage: { label: "Uso e custo", path: "/usage" },
   omni_measures: { label: "Medições do Omni", path: "/agent" },
   getting_started: { label: "Primeiros passos", path: "/getting-started" },
 };

package/studio/shared/schemas/cost.ts

@@ -0,0 +1,10 @@
+/* Agent cost (settings Uso e custo): ?days=N limits the window, none = everything recorded. */
+
+import { z } from "zod";
+
+export const costQuery = z.object({
+  days: z
+    .string()
+    .regex(/^\d{1,4}$/)
+    .optional(),
+});

package/studio/shared/types/api.ts

@@ -337,10 +337,11 @@ export type SoundBed = {
 } | null;
 /* an area cut (tools/cuts.mjs), in scenes.json time */
 export type SoundCut = { from: number; to: number };
-/* a sound of the kit or of the video's sfx/ */
+/* a sound of a kit or of the video's sfx/ (a kit's effect is named "kit/name.mp3") */
 export type SoundEffectInfo = {
   name: string;
   origin: "kit" | "video";
+  kit?: string | null;
   role: string | null;
   title: string;
   music: boolean;
@@ -356,6 +357,7 @@ export type SoundClip = { from: number; to: number; offset: number; speed?: numb
 export type SoundCatalog = {
   kit: SoundEffectInfo[];
   video: SoundEffectInfo[];
+  defaultKit?: string;
   roles: Record<string, { db: number; stretchable?: boolean }>;
   level_db: number;
   ducking: { db: number };
@@ -939,6 +941,44 @@ export type UsageData = {
 
 export type Usage = UsageData | { error: string };
 
+/* what the agents spent (tools/lib/cost.mjs): the Claude turns in .sessions/, by video, stage and model */
+export type AgentCostVideo = {
+  video: string;
+  type: string;
+  total: number;
+  turns: number;
+  first: string;
+  last: string;
+  stages: Record<string, number>;
+  models: Record<string, number>;
+};
+export type AgentCostFork = {
+  video: string;
+  session: string;
+  turn: number;
+  stage: string;
+  label: string;
+  cost: number;
+  messages: number;
+};
+export type AgentCost = {
+  /* the window in days; null = everything recorded */
+  days: number | null;
+  total: number;
+  turns: number;
+  sessions: number;
+  /* turns that never closed: their cost is an estimate */
+  partial: number;
+  /* turns with no dollar cost (Codex) */
+  unmeasured: number;
+  by_kind: Record<string, number>;
+  by_stage: Record<string, number>;
+  by_model: Record<string, number>;
+  by_day: { day: string; cost: number }[];
+  by_video: AgentCostVideo[];
+  top_forks: AgentCostFork[];
+};
+
 /* --- settings ---------------------------------------------------------------------------- */
 export type KeyStatus = { name: string; masked: string | null; in_env: boolean };
 
@@ -1184,6 +1224,42 @@ export type RunnerProblem =
   | { reason: "protocol"; at: string; side: "mac" | "cloud"; host?: string }
   | { reason: "revoked"; at: string; name?: string };
 
+/* the first-time setup the CLI reports to the user's cloud while the studio isn't connected yet
+   (tools/lib/setup-progress.mjs; read from GET /api/cloud/config, key `setup`) */
+export type SetupStepState = "pending" | "running" | "done" | "error";
+export type SetupStep = { id: string; label: string; detail: string; state: SetupStepState; error?: string };
+export type SetupRecord = {
+  v: 1;
+  state: "running" | "done" | "error";
+  device: string;
+  started_at: number;
+  updated_at: number;
+  steps: SetupStep[];
+  /* the last time the process waiting for a retry looked (the page offers "Tentar de novo" while it is recent) and the
+     id of the last retry request it answered */
+  watching_at?: number;
+  handled?: string;
+};
+/* what the page writes to ask for a retry (`setup_retry` of the cloud config): a step id, or "all" */
+export type SetupRetryRequest = { id: string; step: string; at: number };
+
+/* who is using the studio: the menu's user card (GET /api/me here; the Worker's /session/me when hosted).
+   `source` is where a local studio found them: the Omni login, or the Claude Code account */
+export type Me = { name: string | null; email: string; image: string | null; source: "omni" | "claude" | "session" };
+
+/* the computers signed in to the hosted studio, and the actions that went through to them
+   (the Worker's /session/computers and /session/audit: cloud/studio/src/account-routes.mjs) */
+export type Computer = {
+  id: string;
+  name: string;
+  /* "login": entered with the plugin; "key": the old pairing key (tools/runner.mjs) */
+  kind: "login" | "key";
+  created_at: number;
+  last_seen: number | null;
+  online: boolean;
+};
+export type AuditEntry = { at: number; who: string; method: string; path: string; status: number; ms: number };
+
 /* --- the admin panel (GET /api/admin) ------------------------------------------------------------ */
 export type OmniAdminSettings = {
   enabled: boolean;