@crievo/omni 0.0.0-stage → 0.1.1

package/studio/api/services/sessions.ts

@@ -0,0 +1,1007 @@
+/* Agent sessions opened from the UI. Each turn is a `claude -p` (or a `codex exec`) without a
+   terminal, at the omnivideo root and with the project's skills; the next
+   reply resumes the same session (--resume). It is the same work as the chat, only
+   the UI is the one reading and replying.
+
+   Accounts (tools/lib/agents.mjs): a new session goes to the next account of the rotation and
+   stays there while it is free. A turn that hits the account's limit sets it aside and the
+   session carries on in the next free one: Claude to Claude with the transcript copied over
+   (same conversation), anything else as a new conversation that gets the story so far.
+
+   The studio keeps no state in memory: each session is a dir
+   .sessions/<id>/ with session.json (who, what, the turns) and one
+   turn-<n>.jsonl per turn, claude's stream-json output (codex's --json events). State comes from
+   there and from the pid: a turn with `result` has ended; without `result` and with a live pid
+   it is running; with neither it was interrupted. claude runs in its own process
+   group and writes straight to the file, so the studio can go down and come back in
+   the middle of a turn without losing anything. */
+
+import {
+  mkdirSync,
+  readdirSync,
+  writeFileSync,
+  renameSync,
+  openSync,
+  closeSync,
+  readSync,
+  statSync,
+  existsSync,
+  rmSync,
+} from "node:fs";
+import { join, relative } from "node:path";
+import { ROOT, CONFIG, PYTHON, CLAUDE_PERSONAL_DIR, readJson } from "./root";
+import {
+  PROVIDER_LABEL,
+  accountsOf,
+  codexBin,
+  codexResetOf,
+  codexSettings,
+  copyClaudeSession,
+  envFor,
+  isLimitText,
+  isReady,
+  markLimited,
+  noAccountReason,
+  pickAccount,
+} from "../../../tools/lib/agents.mjs";
+import { isAlive } from "./queue";
+import { sessionModel } from "./settings";
+import { LIBRARY_DIR } from "./references";
+
+export const SESSIONS_DIR = join(ROOT, ".sessions");
+
+/* "analysis": the Analytics page session (target "channel"), which runs the av-analysis skill;
+   "edit": a video's editor chat (target = the slug), which runs the av-editor skill;
+   "omni": Omni in Claude mode (target "omni"), after the day's voice quota */
+export type SessionType = "video" | "reference" | "analysis" | "edit" | "omni";
+type Provider = "claude" | "codex";
+type Account = ReturnType<typeof accountsOf>[number];
+type Turn = {
+  n: number;
+  origin: string;
+  prompt: string;
+  pid: number;
+  started_at: string;
+  file: string;
+  /* the account (agents.accounts) and the agent the turn ran on; absent before the accounts,
+     when every turn was Claude on the personal dir */
+  account?: string;
+  provider?: Provider;
+  /* Claude's session id (r.id, or a new one after a handoff); Codex's thread is read from the file */
+  engine_id?: string;
+  /* the turn started a new conversation on another account, carrying the story so far */
+  handoff?: boolean;
+  /* a failover turn: the request it carries on */
+  request?: string;
+};
+/* config_dir: the Claude dir (CLAUDE_CONFIG_DIR) of a session from before the accounts; null = ~/.claude */
+type SessionRecord = {
+  id: string;
+  type: SessionType;
+  target: string;
+  dir: string;
+  title: string;
+  created_at: string;
+  config_dir?: string | null;
+  turns: Turn[];
+};
+type TurnResult = {
+  duration_ms: number | null;
+  cost: number | null;
+  models: Record<string, number>;
+  text: string;
+  error: boolean;
+  denied: string[];
+  /* the account hit its usage limit in this turn: when it resets (ms), null when unknown */
+  limited: { until: number | null } | null;
+  /* Codex reports tokens, not dollars */
+  tokens?: number | null;
+};
+export type SessionState = "running" | "stopped" | "error" | "interrupted";
+
+const CLAUDE = CONFIG.studio?.claude ?? {};
+const BASH_MS: number = CLAUDE.bash_timeout_ms ?? 7_200_000;
+
+/* --- reading ------------------------------------------------------------------ */
+const isValid = (id: string) => /^[0-9a-f-]{36}$/.test(id);
+
+function readRecord(id: string): SessionRecord | null {
+  return isValid(id) ? readJson<SessionRecord>(join(SESSIONS_DIR, id, "session.json")) : null;
+}
+
+function writeRecord(r: SessionRecord) {
+  const file = join(SESSIONS_DIR, r.id, "session.json");
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(r, null, 2) + "\n");
+  renameSync(tmp, file);
+}
+
+/* The end of the turn and what Claude was doing last, read from the tail of the jsonl.
+   An image Read puts megabytes of base64 on a single line: the tail is enough,
+   because `result` is always the last thing in the turn. */
+type TurnInfo = { result: TurnResult | null; now: string | null };
+const readCache = new Map<string, { size: number; mtime: number; info: TurnInfo }>();
+
+const providerOf = (t: Turn): Provider => t.provider ?? "claude";
+const turnInfo = (r: SessionRecord, t: Turn) => readTurn(join(SESSIONS_DIR, r.id, t.file), providerOf(t), t.started_at);
+
+function readTurn(file: string, provider: Provider = "claude", startedAt?: string): TurnInfo {
+  let st: ReturnType<typeof statSync>;
+  try {
+    st = statSync(file);
+  } catch {
+    return { result: null, now: null };
+  }
+  const c = readCache.get(file);
+  if (c && c.size === st.size && c.mtime === st.mtimeMs) return c.info;
+  const from = Math.max(0, st.size - 1_000_000);
+  const buf = Buffer.alloc(st.size - from);
+  const fd = openSync(file, "r");
+  try {
+    readSync(fd, buf, 0, buf.length, from);
+  } finally {
+    closeSync(fd);
+  }
+  const lines = buf.toString("utf8").split("\n");
+  if (provider === "codex") {
+    const info = codexTurn(lines, st.mtimeMs, startedAt);
+    readCache.set(file, { size: st.size, mtime: st.mtimeMs, info });
+    return info;
+  }
+  const info: TurnInfo = { result: null, now: null };
+  /* While a long tool runs (a forked stage is a Skill), claude
+     writes a heartbeat every 30 s. Those after the last action tell
+     how long the UI has been still, and whether the action's result is back
+     (the model is thinking) or not (the tool is still running). Without this, an
+     Opus thinking for five minutes looks stuck. */
+  const beats: number[] = [];
+  let answered = false;
+  for (let i = lines.length - 1; i >= 0 && !info.now; i--) {
+    let o: any;
+    try {
+      o = JSON.parse(lines[i]);
+    } catch {
+      continue;
+    }
+    if (o.type === "result" && !info.result) info.result = turnResult(o);
+    if (o.type === "tool_progress" && o.heartbeat) {
+      beats.push(o.elapsed_time_seconds);
+      continue;
+    }
+    if (
+      o.type === "user" &&
+      Array.isArray(o.message?.content) &&
+      o.message.content.some((c: any) => c.type === "tool_result")
+    )
+      answered = true;
+    if (o.type === "assistant") {
+      /* forked stage: what the subagent does, with its model */
+      const sub = o.parent_tool_use_id ? `↳ ${shortModel(o.message?.model)} ` : "";
+      const last = (o.message?.content ?? [])
+        .filter((x: any) => x.type === "tool_use" || (x.type === "text" && x.text.trim()))
+        .at(-1);
+      if (last)
+        info.now =
+          sub +
+          (last.type === "text"
+            ? last.text.trim().split("\n")[0].slice(0, 200)
+            : `▸ ${last.name}  ${toolSummary(last.name, last.input ?? {})}`);
+    }
+  }
+  /* the limit: a 429 at the end, and the rejected rate_limit_event a few lines before it says when it resets */
+  if (info.result?.error && info.result.limited) {
+    for (let i = lines.length - 1; i >= Math.max(0, lines.length - 80); i--) {
+      if (!lines[i].includes('"rate_limit_event"')) continue;
+      try {
+        const e = JSON.parse(lines[i]).rate_limit_info;
+        if (e?.status === "rejected" && e.resetsAt) {
+          info.result.limited = { until: e.resetsAt * 1000 };
+          break;
+        }
+      } catch {
+        /* a cut line */
+      }
+    }
+  }
+  if (info.now && !info.result && beats.length >= 2) {
+    const s = beats[0] - beats.at(-1)! + 30;
+    const time = s < 60 ? `${s} s` : `${Math.floor(s / 60)} min${s % 60 ? ` ${s % 60} s` : ""}`;
+    info.now += ` — ${answered ? "Pensando" : "esperando a ferramenta"} há ${time}, processo vivo (sinal a cada 30 s)`;
+  }
+  readCache.set(file, { size: st.size, mtime: st.mtimeMs, info });
+  return info;
+}
+
+function turnResult(o: any): TurnResult {
+  return {
+    duration_ms: o.duration_ms ?? null,
+    cost: o.total_cost_usd ?? null,
+    /* includes the spend of forked stages, each on its own model */
+    models: Object.fromEntries(
+      Object.entries(o.modelUsage ?? {}).map(([m, u]: [string, any]) => [shortModel(m), +(u.costUSD ?? 0).toFixed(4)]),
+    ),
+    text:
+      typeof o.result === "string" && o.result.trim()
+        ? o.result
+        : `(o turno terminou sem resposta: ${o.subtype ?? "?"})`,
+    error: !!o.is_error,
+    limited: o.is_error && (o.api_error_status === 429 || isLimitText(o.result)) ? { until: null } : null,
+    denied: (o.permission_denials ?? []).map((d: any) => {
+      const e = d.tool_input ?? {};
+      const target = e.command ?? e.file_path ?? e.url ?? "";
+      return target ? `${d.tool_name}: ${String(target).split("\n")[0].slice(0, 200)}` : d.tool_name;
+    }),
+  };
+}
+
+/* Codex's --json events: item.started/completed (command_execution, agent_message, file_change,
+   mcp_tool_call, web_search, todo_list, reasoning, error), then turn.completed or turn.failed */
+function codexItemLine(it: any): string | null {
+  switch (it?.type) {
+    case "command_execution":
+      return `▸ Bash  $ ${shellOf(it.command)}`;
+    case "file_change":
+      return `▸ Edit  ${(it.changes ?? []).map((c: any) => rel(String(c.path ?? ""))).join(", ")}`;
+    case "mcp_tool_call":
+      return `▸ ${it.server ?? "mcp"}.${it.tool ?? "?"}`;
+    case "web_search":
+      return `▸ WebSearch  ${it.query ?? ""}`;
+    case "todo_list":
+      return `▸ TodoWrite  ${(it.items ?? []).length} tarefas`;
+    case "agent_message":
+    case "reasoning":
+    case "error":
+      return null;
+    default:
+      return it?.type ? `▸ ${it.type}` : null;
+  }
+}
+
+/* `/bin/zsh -lc 'cmd'` → cmd */
+const shellOf = (c: unknown) =>
+  String(c ?? "")
+    .replace(/^\S*sh -lc '([\s\S]*)'$/, "$1")
+    .split("\n")[0]
+    .slice(0, 240);
+
+function codexTurn(lines: string[], mtime: number, startedAt?: string): TurnInfo {
+  const info: TurnInfo = { result: null, now: null };
+  let said = "";
+  let lastError = "";
+  for (const line of lines) {
+    let o: any;
+    try {
+      o = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const it = o.item;
+    if (o.type === "item.started" || o.type === "item.completed") {
+      if (it?.type === "agent_message" && it.text?.trim()) {
+        said = it.text;
+        info.now = it.text.trim().split("\n")[0].slice(0, 200);
+      } else if (it?.type === "error") lastError = it.message ?? lastError;
+      else if (it?.type === "reasoning") info.now = "Pensando";
+      else info.now = codexItemLine(it) ?? info.now;
+    }
+    if (o.type === "error") lastError = o.message ?? lastError;
+    const duration_ms = startedAt ? Math.max(0, Math.round(mtime - Date.parse(startedAt))) : null;
+    if (o.type === "turn.completed") {
+      const u = o.usage ?? {};
+      info.result = {
+        duration_ms,
+        cost: null,
+        models: {},
+        tokens: (u.input_tokens ?? 0) + (u.output_tokens ?? 0) || null,
+        text: said.trim() ? said : "(o turno terminou sem resposta)",
+        error: false,
+        denied: [],
+        limited: null,
+      };
+    }
+    if (o.type === "turn.failed") {
+      const message = String(o.error?.message ?? lastError ?? "erro");
+      info.result = {
+        duration_ms,
+        cost: null,
+        models: {},
+        text: `Erro do Codex: ${readableError(message)}`,
+        error: true,
+        denied: [],
+        limited: isLimitText(message) ? { until: codexResetOf(message) } : null,
+      };
+    }
+  }
+  return info;
+}
+
+/* the API error inside Codex's message, when it is one: `{"error":{"message":…}}` */
+function readableError(message: string): string {
+  try {
+    const j = JSON.parse(message);
+    return String(j?.error?.message ?? j?.message ?? message);
+  } catch {
+    return message;
+  }
+}
+
+function stateOf(r: SessionRecord): { state: SessionState; result: TurnResult | null; now: string | null } {
+  const t = r.turns.at(-1);
+  if (!t) return { state: "interrupted", result: null, now: null };
+  const { result, now } = turnInfo(r, t);
+  if (result) return { state: result.error ? "error" : "stopped", result, now };
+  return { state: isAlive(t.pid) ? "running" : "interrupted", result: null, now };
+}
+
+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);
+  const account = t ? accountOfTurn(r, t) : null;
+  let activity = Date.parse(r.created_at);
+  try {
+    activity = statSync(join(SESSIONS_DIR, r.id, t!.file)).mtimeMs;
+  } catch {
+    /* turn has no output yet */
+  }
+  return {
+    id: r.id,
+    type: r.type,
+    target: r.target,
+    title: r.title,
+    created_at: r.created_at,
+    state,
+    activity: Math.round(activity),
+    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),
+    agent: t ? { provider: providerOf(t), account: account?.id ?? null, label: account?.label ?? null } : null,
+  };
+}
+export type SessionSummary = ReturnType<typeof summarizeSession>;
+
+export function listSessions(): SessionSummary[] {
+  if (!existsSync(SESSIONS_DIR)) return [];
+  const all: SessionSummary[] = [];
+  for (const id of readdirSync(SESSIONS_DIR)) {
+    const r = readRecord(id);
+    if (r) all.push(summarizeSession(r));
+  }
+  return all.sort((a, b) => b.activity - a.activity);
+}
+
+export function getSession(id: string) {
+  const r = readRecord(id);
+  return r
+    ? {
+        ...summarizeSession(r),
+        history: r.turns.map(t => ({ ...t, result: turnInfo(r, t).result })),
+      }
+    : null;
+}
+
+/* the most recent session of a video or a reference */
+export function latestSessionFor(type: SessionType, target: string): SessionSummary | null {
+  return listSessions().find(s => s.type === type && s.target === target) ?? null;
+}
+
+/* --- running ---------------------------------------------------------------------- */
+const systemContext =
+  () => `Sessão aberta pelo omnivideo studio (http://127.0.0.1:5432), sem terminal: o usuário lê o que você escreve e responde pela tela, e ninguém aprova permissão. O modo de permissão é auto: o comum roda sozinho e o arriscado é negado na hora, sem volta nesta sessão.
+- A pasta de trabalho já é a raiz do omnivideo; o Python do projeto é ${PYTHON}.
+- Ferramentas pesadas (voz, legenda, render, som, montagem) em primeiro plano, não em segundo plano: o limite do Bash aqui é de ${Math.round(BASH_MS / 60_000)} min, e a fila da máquina espera a vez sozinha.
+- Não confira serviços com curl: o studio mostra VoiceStudio e Premiere (o Premiere é opcional: a etapa 8 é o assemble.mjs, por ffmpeg). Se uma ferramenta falhar por serviço fora do ar, pare e diga o que abrir.
+- Aprovação do roteiro (approval.mjs wait --script, logo depois do av-script) e das cenas (approval.mjs wait) em primeiro plano: ela segura até o prazo de aprovação automática (a contagem pausa enquanto o usuário edita) e segue sozinha; saindo com 3, chame a etapa de novo com o pedido (no roteiro, av-script com \`ajustar roteiro: «…»\`); saindo com 4, pare: o studio retoma esta sessão quando a rodada terminar.
+Quando parar (na aprovação do roteiro ou das cenas com saída 4, num bloqueio ou na entrega), termine com uma mensagem curta: o que foi feito, o que você precisa do usuário e onde olhar no studio.`;
+
+/* what Codex needs on top of the same context: it runs skills written for Claude Code */
+const CODEX_NOTES = `Você é o Codex rodando as skills do omnivideo, escritas para o Claude Code:
+- As skills do projeto estão em .agents/skills (as mesmas de .claude/skills). Os campos model, effort e context do frontmatter são do Claude: ignore.
+- Onde uma skill ou o CLAUDE.md manda abrir um fork, um subagente ou a ferramenta Agent, use sua ferramenta de subagentes se houver; senão, faça a etapa você mesmo, em sequência.
+- A sandbox não deixa o Chrome abrir: os comandos que renderizam (tools/render.mjs, tools/build-motion.mjs, tools/wireframe.mjs, tools/thumbnail.mjs, tools/carousel.mjs, tools/reference.mjs) pedem para rodar fora da sandbox já na primeira tentativa; o mesmo para um comando que falhar por permissão.
+- Onde a skill fala do Claude in Chrome (sons do Epidemic), use o navegador que você tiver; se não houver, pare e diga.`;
+
+const liveConfig = () => readJson<any>(join(ROOT, "omnivideo.config.json")) ?? CONFIG;
+const engineArgs = (plan: Plan) =>
+  plan.engine.kind === "new" ? (plan.engine.id ? ["--session-id", plan.engine.id] : []) : ["--resume", plan.engine.id];
+
+function claudeArgs(r: SessionRecord, plan: Plan): string[] {
+  const allow: string[] = (CLAUDE.allow ?? []).map((p: string) => p.replaceAll("{python}", PYTHON));
+  return [
+    Bun.which(CLAUDE.bin ?? "claude") ?? CLAUDE.bin ?? "claude",
+    "-p",
+    plan.prompt,
+    ...engineArgs(plan),
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    /* reread every turn; `auto`: the classifier approves the usual and denies the risky,
+       and with --permission-prompts none nobody needs to answer */
+    "--permission-mode",
+    liveConfig()?.studio?.claude?.permission_mode ?? "auto",
+    "--permission-prompts",
+    "none",
+    "--add-dir",
+    LIBRARY_DIR,
+    /* sound effects only from Epidemic, captured in Chrome (skill av-motion, Sound) */
+    "--chrome",
+    "--append-system-prompt",
+    systemContext(),
+    /* orchestrator or reference: `models` in the config, reread every turn; forked
+       stages bring their own model in the skill frontmatter */
+    ...(m => [...(m?.model ? ["--model", m.model] : []), ...(m?.effort ? ["--effort", m.effort] : [])])(
+      sessionModel(r.type),
+    ),
+    ...(CLAUDE.budget_usd ? ["--max-budget-usd", String(CLAUDE.budget_usd)] : []),
+    /* variadic: goes last */
+    ...(allow.length ? ["--allowedTools", ...allow] : []),
+  ];
+}
+
+/* `codex exec` (or `exec resume <thread>`): the same context as developer instructions, CLAUDE.md as
+   the project doc, and a sandbox that writes the project and the library, with network. "auto": what
+   needs to leave the sandbox (Chrome) asks, and Codex's reviewer decides, like Claude's auto mode;
+   "full": no sandbox at all (agents.codex.sandbox). */
+function codexArgs(plan: Plan): string[] {
+  const cfg = liveConfig();
+  const c = codexSettings(cfg);
+  const sandbox =
+    c.sandbox === "full"
+      ? ["--dangerously-bypass-approvals-and-sandbox"]
+      : [
+          "-c",
+          'approval_policy="on-request"',
+          "-c",
+          'approvals_reviewer="auto_review"',
+          "-c",
+          'sandbox_mode="workspace-write"',
+          "-c",
+          "sandbox_workspace_write.network_access=true",
+          "-c",
+          `sandbox_workspace_write.writable_roots=${JSON.stringify([LIBRARY_DIR])}`,
+        ];
+  const opts = [
+    "--json",
+    "--skip-git-repo-check",
+    "-m",
+    c.model,
+    ...(c.effort ? ["-c", `model_reasoning_effort="${c.effort}"`] : []),
+    "-c",
+    'project_doc_fallback_filenames=["CLAUDE.md"]',
+    "-c",
+    `developer_instructions=${JSON.stringify(`${systemContext()}\n${CODEX_NOTES}`)}`,
+    ...sandbox,
+  ];
+  /* a prompt that starts with "-" would read as a flag */
+  const prompt = plan.prompt.startsWith("-") ? ` ${plan.prompt}` : plan.prompt;
+  return [
+    codexBin(cfg),
+    "exec",
+    ...(plan.engine.kind === "resume" ? ["resume", ...opts, plan.engine.id] : opts),
+    prompt,
+  ];
+}
+
+/* a studio opened from inside a chat inherits that session's variables: the account's dir is set
+   here and nothing else is kept (tools/lib/agents.mjs envFor) */
+const agentEnv = (a: Account) =>
+  envFor(a, process.env, { BASH_MAX_TIMEOUT_MS: String(BASH_MS), BASH_DEFAULT_TIMEOUT_MS: String(BASH_MS) });
+
+/* the account a turn ran on; a turn from before the accounts ran on the session's config_dir */
+function accountOfTurn(r: SessionRecord, t: Turn): Account | null {
+  const all = accountsOf(liveConfig());
+  if (t.account) return all.find(a => a.id === t.account) ?? null;
+  const dir = r.config_dir === undefined ? CLAUDE_PERSONAL_DIR : r.config_dir;
+  return all.find(a => a.provider === "claude" && a.dir === dir) ?? null;
+}
+
+/* Codex's thread id: the first event of the turn's file */
+function codexThread(r: SessionRecord, t: Turn): string | null {
+  const file = join(SESSIONS_DIR, r.id, t.file);
+  try {
+    const fd = openSync(file, "r");
+    const buf = Buffer.alloc(4096);
+    try {
+      readSync(fd, buf, 0, buf.length, 0);
+    } finally {
+      closeSync(fd);
+    }
+    return /"thread_id":"([^"]+)"/.exec(buf.toString("utf8"))?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+const engineOf = (r: SessionRecord, t: Turn) =>
+  providerOf(t) === "claude" ? (t.engine_id ?? r.id) : codexThread(r, t);
+
+type Plan = {
+  account: Account;
+  engine: { kind: "new"; id?: string } | { kind: "resume"; id: string };
+  prompt: string;
+  handoff: boolean;
+};
+
+/* Where the next turn runs. The account of the last turn while it is free; otherwise the next one of
+   the rotation: Claude after Claude resumes the same conversation (its transcript copied over),
+   anything else opens a new one that gets the story so far. */
+function planTurn(r: SessionRecord, prompt: string, exclude: string[] = []): Plan {
+  const cfg = liveConfig();
+  const last = r.turns.at(-1);
+  const prev = last ? accountOfTurn(r, last) : null;
+  const prevEngine = last ? engineOf(r, last) : null;
+  if (prev && prevEngine && !exclude.includes(prev.id) && isReady(ROOT, prev))
+    return { account: prev, engine: { kind: "resume", id: prevEngine }, prompt, handoff: false };
+  const a: Account | null = pickAccount(ROOT, cfg, { exclude });
+  if (!a) throw new Error(noAccountReason(ROOT, cfg));
+  const fresh = (p: string, handoff: boolean): Plan => ({
+    account: a,
+    engine: { kind: "new", id: a.provider === "claude" ? (last ? crypto.randomUUID() : r.id) : undefined },
+    prompt: p,
+    handoff,
+  });
+  if (!last) return fresh(prompt, false);
+  if (a.provider === "claude" && providerOf(last) === "claude" && prev && prevEngine) {
+    if (copyClaudeSession(prev, a, ROOT, prevEngine))
+      return { account: a, engine: { kind: "resume", id: prevEngine }, prompt, handoff: false };
+  }
+  return fresh(handoffPrompt(r, prompt, prev), true);
+}
+
+const clip = (s: string, n: number) => (s.length > n ? `${s.slice(0, n)}…` : s);
+
+/* the story so far, for a new conversation on another account (prose to the agent: Portuguese) */
+function handoffPrompt(r: SessionRecord, prompt: string, prev: Account | null): string {
+  const first = r.turns[0];
+  const recent = r.turns
+    .slice(-4)
+    .map(t => {
+      const res = turnInfo(r, t).result;
+      return `- ${ORIGIN_LABEL[t.origin] ?? t.origin}: «${clip(t.request ?? t.prompt, 1200)}»\n  ${
+        res ? `resposta: «${clip(res.text, 1500)}»` : "(turno interrompido)"
+      }`;
+    })
+    .join("\n");
+  const where = r.type === "video" ? ` (rode ${PYTHON} tools/omnivideo.py status ${rel(r.dir)})` : "";
+  return `Esta sessão do omnivideo vinha rodando em outra conta de agente${
+    prev ? ` (${PROVIDER_LABEL[prev.provider]}, ${prev.label})` : ""
+  }, que não pode seguir: bateu o limite de uso ou saiu da lista. Você continua o trabalho numa conversa nova, sem o histórico dela.
+Pedido que abriu a sessão: «${clip(first?.request ?? first?.prompt ?? "", 3000)}»
+Últimos turnos:
+${recent}
+O estado real está nos arquivos${where}: confira antes de agir e não refaça o que já está pronto.
+
+Agora: ${prompt}`;
+}
+
+let onChange: () => void = () => {};
+export function onSessionsChange(fn: () => void) {
+  onChange = fn;
+}
+
+/* what to check when a turn ends (the scenes approval decided in the middle of it) */
+const afterTurn: ((type: SessionType, target: string) => void)[] = [];
+export function onTurnEnd(fn: (type: SessionType, target: string) => void) {
+  afterTurn.push(fn);
+}
+
+function startTurn(
+  r: SessionRecord,
+  prompt: string,
+  origin: string,
+  opts: { request?: string; exclude?: string[] } = {},
+) {
+  const plan = planTurn(r, prompt, opts.exclude);
+  const n = r.turns.length + 1;
+  const file = `turn-${n}.jsonl`;
+  const fd = openSync(join(SESSIONS_DIR, r.id, file), "a");
+  let p: ReturnType<typeof Bun.spawn>;
+  try {
+    p = Bun.spawn(plan.account.provider === "claude" ? claudeArgs(r, plan) : codexArgs(plan), {
+      cwd: ROOT,
+      stdin: "ignore",
+      stdout: fd,
+      stderr: fd,
+      env: agentEnv(plan.account),
+      detached: true,
+    });
+  } finally {
+    closeSync(fd);
+  }
+  p.unref();
+  r.turns.push({
+    n,
+    origin,
+    prompt,
+    pid: p.pid,
+    started_at: new Date().toISOString(),
+    file,
+    account: plan.account.id,
+    provider: plan.account.provider,
+    ...(plan.account.provider === "claude" ? { engine_id: plan.engine.id } : {}),
+    ...(plan.handoff ? { handoff: true } : {}),
+    ...(opts.request ? { request: opts.request } : {}),
+  });
+  writeRecord(r);
+  p.exited.then(() => {
+    failover(r.id, n);
+    onChange();
+    for (const fn of afterTurn) {
+      try {
+        fn(r.type, r.target);
+      } catch {
+        /* one listener does not take the studio down */
+      }
+    }
+  });
+}
+
+/* The turn ended on the account's limit: the account is set aside until it resets and the same
+   request carries on in the next free one. A chain of failovers stops once every account had its
+   turn; with none free the session stays stopped on the limit message. */
+function failover(id: string, n: number) {
+  const r = readRecord(id);
+  const t = r?.turns.at(-1);
+  if (!r || !t || t.n !== n) return;
+  const res = turnInfo(r, t).result;
+  if (!res?.limited) return;
+  const acc = accountOfTurn(r, t);
+  if (acc) markLimited(ROOT, acc.id, res.limited.until, res.text.slice(0, 200));
+  let chain = 0;
+  for (let i = r.turns.length - 1; i >= 0 && r.turns[i].origin === "failover"; i--) chain++;
+  if (chain >= accountsOf(liveConfig()).length) return;
+  const request = t.request ?? t.prompt;
+  try {
+    startTurn(
+      r,
+      `A conta anterior bateu o limite de uso no meio deste pedido. Continue de onde parou, sem refazer o que já ficou pronto: «${request}»`,
+      "failover",
+      { request, exclude: acc ? [acc.id] : [] },
+    );
+  } catch {
+    /* no account free: the turn's own answer says the limit */
+  }
+}
+
+export type ApiResult = { ok: boolean; output?: string; error?: string; session?: string };
+
+export function openSession(
+  type: SessionType,
+  target: string,
+  dir: string,
+  title: string,
+  prompt: string,
+  origin = "request",
+): ApiResult {
+  const active = latestSessionFor(type, target);
+  if (active?.state === "running")
+    return {
+      ok: false,
+      error: "o agente já está trabalhando aqui: espere o turno terminar ou pare a sessão",
+      session: active.id,
+    };
+  const r: SessionRecord = {
+    id: crypto.randomUUID(),
+    type,
+    target,
+    dir,
+    title,
+    created_at: new Date().toISOString(),
+    turns: [],
+  };
+  mkdirSync(join(SESSIONS_DIR, r.id), { recursive: true });
+  try {
+    startTurn(r, prompt, origin);
+  } catch (e: any) {
+    rmSync(join(SESSIONS_DIR, r.id), { recursive: true, force: true });
+    return { ok: false, error: `não deu para abrir o agente: ${e.message}` };
+  }
+  return { ok: true, output: "o agente começou", session: r.id };
+}
+
+export function replyToSession(id: string, message: string, origin = "user"): ApiResult {
+  const r = readRecord(id);
+  if (!r) return { ok: false, error: "sessão não encontrada" };
+  const text = message.trim();
+  if (!text) return { ok: false, error: "escreva a mensagem" };
+  if (stateOf(r).state === "running")
+    return { ok: false, error: "o agente ainda está no meio do turno: espere ele parar ou pare a sessão", session: id };
+  try {
+    startTurn(r, text, origin);
+  } catch (e: any) {
+    return { ok: false, error: `não deu para retomar o agente: ${e.message}` };
+  }
+  return { ok: true, output: "o agente retomou a sessão", session: id };
+}
+
+/* the whole group: claude and the tools it opened */
+export function stopSession(id: string): ApiResult {
+  const r = readRecord(id);
+  const t = r?.turns.at(-1);
+  if (!r || !t) return { ok: false, error: "sessão não encontrada" };
+  if (stateOf(r).state !== "running") return { ok: false, error: "a sessão não está rodando" };
+  try {
+    process.kill(-t.pid, "SIGTERM");
+  } catch {
+    try {
+      process.kill(t.pid, "SIGTERM");
+    } catch {
+      /* already gone */
+    }
+  }
+  return { ok: true, output: "sessão parada: o que já estava gravado continua lá" };
+}
+
+/* --- transcript ------------------------------------------------------------------
+   The stream-json becomes readable text: what Claude wrote, each tool on
+   one line, tool errors and denied permissions. Successful tool results
+   are left out (they are the whole file it read). */
+const rel = (p: string) => {
+  const r = relative(ROOT, p);
+  return r.startsWith("..") ? p : r;
+};
+
+function toolSummary(name: string, e: any): string {
+  switch (name) {
+    case "Bash":
+      return `$ ${String(e.command ?? "")
+        .split("\n")[0]
+        .slice(0, 240)}`;
+    case "Read":
+    case "Write":
+    case "Edit":
+    case "NotebookEdit":
+      return rel(String(e.file_path ?? e.notebook_path ?? ""));
+    case "Skill":
+      return `${e.skill ?? e.name ?? ""}${e.args ? ` ${e.args}` : ""}`;
+    case "Glob":
+    case "Grep":
+      return String(e.pattern ?? "");
+    case "WebFetch":
+      return String(e.url ?? "");
+    case "WebSearch":
+      return String(e.query ?? "");
+    case "Task":
+    case "Agent":
+      return String(e.description ?? "");
+    case "TodoWrite":
+      return `${(e.todos ?? []).length} tarefas`;
+    default:
+      return "";
+  }
+}
+
+const textOf = (c: unknown): string =>
+  typeof c === "string" ? c : Array.isArray(c) ? c.map(x => (x?.type === "text" ? x.text : "")).join("") : "";
+
+/* claude-sonnet-5-5 → sonnet 5.5; claude-haiku-4-5-20251001 → haiku 4.5 */
+const shortModel = (m: unknown) => {
+  const r = /^claude-([a-z]+)-(\d+)(?:-(\d{1,2}))?(?:-\d{8})?$/.exec(String(m ?? ""));
+  return r ? `${r[1]} ${r[2]}${r[3] ? `.${r[3]}` : ""}` : String(m ?? "?");
+};
+
+/* one Codex event as the same readable text */
+function transcribeCodex(o: any): string {
+  const it = o.item;
+  if (o.type === "item.completed" && it?.type === "agent_message" && it.text?.trim()) return `\n${it.text.trim()}\n\n`;
+  if (o.type === "item.started" && it) {
+    const line = codexItemLine(it);
+    return line ? `${line}\n` : "";
+  }
+  if (o.type === "item.completed" && it?.type === "command_execution" && it.exit_code && it.exit_code !== 0)
+    return `  ✕ ${
+      String(it.aggregated_output ?? "")
+        .trim()
+        .split("\n")
+        .slice(-8)
+        .join("\n    ")
+        .slice(0, 900) || `saiu com ${it.exit_code}`
+    }\n`;
+  if (
+    o.type === "item.completed" &&
+    (it?.type === "file_change" || it?.type === "web_search") &&
+    it.status === "failed"
+  )
+    return `  ✕ ${it.type} falhou\n`;
+  if (o.type === "item.completed" && it?.type === "error") return `  ⚠ ${it.message}\n`;
+  if (o.type === "error") return `  ✕ ${readableError(String(o.message ?? ""))}\n`;
+  if (o.type === "turn.completed") {
+    const u = o.usage ?? {};
+    const tokens = (u.input_tokens ?? 0) + (u.output_tokens ?? 0);
+    return `── turno terminou${tokens ? ` · ${Math.round(tokens / 1000)} mil tokens` : ""}\n`;
+  }
+  if (o.type === "turn.failed") return `── turno terminou com erro: ${readableError(String(o.error?.message ?? ""))}\n`;
+  return "";
+}
+
+export function transcribeLine(line: string, provider: Provider = "claude"): string {
+  if (!line.trim()) return "";
+  let o: any;
+  try {
+    o = JSON.parse(line);
+  } catch {
+    /* codex notes on stderr that it reads stdin (the studio gives it none) */
+    return provider === "codex" && line.startsWith("Reading additional input from stdin") ? "" : `${line}\n`;
+  }
+  if (provider === "codex") return transcribeCodex(o);
+  /* forked stage: only tools and errors, indented, with the subagent's model */
+  if (o.parent_tool_use_id) {
+    if (o.type === "assistant") {
+      return (o.message?.content ?? [])
+        .filter((c: any) => c.type === "tool_use")
+        .map((c: any) => `    ↳ ${shortModel(o.message?.model)} ▸ ${c.name}  ${toolSummary(c.name, c.input ?? {})}\n`)
+        .join("");
+    }
+    if (o.type === "user" && Array.isArray(o.message?.content)) {
+      return o.message.content
+        .filter(
+          (c: any) =>
+            c.type === "tool_result" &&
+            c.is_error &&
+            !textOf(c.content).startsWith("Permission for this tool use was denied"),
+        )
+        .map(
+          (c: any) => `      ✕ ${textOf(c.content).trim().split("\n").slice(0, 4).join("\n        ").slice(0, 500)}\n`,
+        )
+        .join("");
+    }
+    return "";
+  }
+  if (o.type === "assistant") {
+    return (o.message?.content ?? [])
+      .map((c: any) =>
+        c.type === "text" && c.text.trim()
+          ? `\n${c.text.trim()}\n\n`
+          : c.type === "tool_use"
+            ? `▸ ${c.name}  ${toolSummary(c.name, c.input ?? {})}\n`
+            : "",
+      )
+      .join("");
+  }
+  if (o.type === "user" && Array.isArray(o.message?.content)) {
+    return o.message.content
+      .filter(
+        (c: any) =>
+          c.type === "tool_result" &&
+          c.is_error &&
+          !textOf(c.content).startsWith("Permission for this tool use was denied"),
+      )
+      .map((c: any) => `  ✕ ${textOf(c.content).trim().split("\n").slice(0, 8).join("\n    ").slice(0, 900)}\n`)
+      .join("");
+  }
+  if (o.type === "system" && o.subtype === "init") return `· ${o.model} · permissão ${o.permissionMode}\n`;
+  if (o.type === "system" && o.subtype === "permission_denied")
+    return `  ⊘ negado: ${o.tool_name} pedia aprovação, e esta sessão não tem quem aprove\n`;
+  if (o.type === "system" && o.subtype === "compact_boundary") return "· contexto compactado\n";
+  if (o.type === "result") {
+    const f = turnResult(o);
+    const dur = f.duration_ms != null ? `${Math.round(f.duration_ms / 60_000)} min` : "";
+    const byModel = Object.entries(f.models)
+      .filter(([, c]) => c >= 0.005)
+      .map(([m, c]) => `${m} ${c.toFixed(2)}`)
+      .join(" · ");
+    const cost = f.cost != null ? `US$ ${f.cost.toFixed(2)}${byModel ? ` (${byModel})` : ""}` : "";
+    return `── ${f.error ? `turno terminou com erro (${o.subtype})` : "turno terminou"}${dur ? ` · ${dur}` : ""}${cost ? ` · ${cost}` : ""}\n`;
+  }
+  return "";
+}
+
+const ORIGIN_LABEL: Record<string, string> = {
+  request: "pedido feito na tela",
+  user: "você",
+  resume: "você, retomando",
+  /* sessions from before the preview stage was dropped: nothing produces these anymore */
+  "preview-approved": "prévia aprovada na tela",
+  "preview-rejected": "prévia reprovada na tela",
+  "scenes-approval": "cenas decididas na tela",
+  "script-approval": "roteiro decidido na tela",
+  /* the carousel requests (api/services/carousel.ts): the live log header showed the raw PT origin */
+  carousel: "carrossel",
+  /* the account hit its limit: the same request in the next one (failover) */
+  failover: "limite da conta: segue em outra",
+};
+const turnHeader = (r: SessionRecord, t: Turn) =>
+  `\n▶ ${ORIGIN_LABEL[t.origin] ?? t.origin} · ${new Date(t.started_at).toLocaleTimeString("pt-BR", { hour: "2-digit", minute: "2-digit" })} · ${
+    PROVIDER_LABEL[providerOf(t)]
+  }${(a => (a ? ` (${a.label})` : ""))(accountOfTurn(r, t))}${t.handoff ? " · conversa nova, com o resumo" : ""}\n` +
+  `${t.prompt.length > 900 ? t.prompt.slice(0, 900) + "…" : t.prompt}\n\n`;
+
+/* SSE: the whole session so far, turn by turn, and what arrives in the last one.
+   Ends when the last turn stops; a new turn needs another connection. */
+export function streamSessionLog(id: string, req: Request): Response {
+  if (!readRecord(id)) return new Response("sessão não encontrada", { status: 404 });
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  let i = 0;
+  let pos = 0;
+  let rest = new Uint8Array(0);
+  let headerSent = false;
+  let busy = false;
+  let closed = false;
+  let timer: ReturnType<typeof setInterval>;
+  const stop = () => {
+    closed = true;
+    clearInterval(timer);
+  };
+  const body = new ReadableStream({
+    start(ctrl) {
+      const send = (event: string, data: unknown) =>
+        ctrl.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
+      const check = () => {
+        if (busy || closed) return;
+        busy = true;
+        try {
+          const r = readRecord(id);
+          if (!r) {
+            stop();
+            ctrl.close();
+            return;
+          }
+          let output = "";
+          while (i < r.turns.length) {
+            const t = r.turns[i];
+            if (!headerSent) {
+              output += turnHeader(r, t);
+              headerSent = true;
+            }
+            const file = join(SESSIONS_DIR, id, t.file);
+            /* state before size: a turn that has already ended here has written everything */
+            const isLast = i === r.turns.length - 1;
+            const ended = !isLast || stateOf(r).state !== "running";
+            let size = 0;
+            try {
+              size = statSync(file).size;
+            } catch {
+              /* no output yet */
+            }
+            if (size > pos) {
+              const chunk = Buffer.alloc(size - pos);
+              const fd = openSync(file, "r");
+              try {
+                readSync(fd, chunk, 0, chunk.length, pos);
+              } finally {
+                closeSync(fd);
+              }
+              pos = size;
+              const joined = new Uint8Array(rest.length + chunk.length);
+              joined.set(rest);
+              joined.set(chunk, rest.length);
+              const cut = joined.lastIndexOf(10);
+              rest = joined.slice(cut + 1);
+              if (cut >= 0) {
+                for (const line of decoder.decode(joined.slice(0, cut)).split("\n"))
+                  output += transcribeLine(line, providerOf(t));
+              }
+            }
+            if (!ended) break;
+            if (rest.length) {
+              output += transcribeLine(decoder.decode(rest), providerOf(t));
+              rest = new Uint8Array(0);
+            }
+            if (!turnInfo(r, t).result) output += "── turno interrompido antes de terminar\n";
+            i++;
+            pos = 0;
+            headerSent = false;
+          }
+          if (output) send("log", output);
+          if (i >= r.turns.length) {
+            send("end", { state: stateOf(r).state });
+            stop();
+            ctrl.close();
+          }
+        } catch {
+          /* client left in the middle of a read */
+          stop();
+        } finally {
+          busy = false;
+        }
+      };
+      timer = setInterval(check, 500);
+      check();
+      req.signal.addEventListener("abort", stop);
+    },
+    cancel: stop,
+  });
+  return new Response(body, { headers: { "content-type": "text/event-stream", "cache-control": "no-cache" } });
+}