@crievo/omni 0.0.0-stage → 0.1.1

package/studio/api/services/omnichat.ts

@@ -0,0 +1,624 @@
+/* Instagram comment omnichat from the UI: the same `tools/omnichat.mjs`
+   as the terminal. The rule lives in <dir>/omnichat.json (key instagram) and what the
+   tool did with each comment in <dir>/omnichat-record.json; the UI reads
+   the rule straight from the file and the record through `log --json`, and writes only through the CLI.
+
+   The dir is a video's (videos/<slug>, the Reel), that of the same content's carousel
+   (videos/<slug>/carousel) or that of a post from outside omnivideo (.omnichat/posts/<code>,
+   created by `post`: Reel, carousel or photo). `status --json` asks the Instagram
+   API (the account and the comments permission): that part is cached for
+   2 min; agent, pause and rules are read on the spot, without the API. */
+
+import { readdirSync, existsSync, statSync, realpathSync } from "node:fs";
+import { join, relative, dirname, basename } from "node:path";
+import { NODE, ROOT, TOOLS_DIR, run, readJson } from "./root";
+import { videoDirs } from "./videos";
+import { videoLink, narrationKeyword } from "../../../tools/omnichat.mjs";
+import { resolveOmnichatConfig } from "../../../tools/lib/omnichat/config.mjs";
+
+type Result = { ok: true; output: string } | { ok: false; error: string };
+
+const OMNICHAT = join(TOOLS_DIR, "omnichat.mjs");
+const OMNICHAT_DIR = join(ROOT, ".omnichat");
+const POSTS_DIR = join(OMNICHAT_DIR, "posts");
+const CODE_RE = /^[\w-]{1,64}$/;
+
+const joinOutput = (r: { stdout: string; stderr: string }) =>
+  [r.stdout, r.stderr]
+    .map(s => s.trim())
+    .filter(Boolean)
+    .join("\n");
+/* the CLI writes "erro: …" to stderr */
+const stripPrefix = (s: string) => s.replace(/^erro: /gm, "");
+/* exit 2 is the CLI help: the command or the dir were not recognized */
+const failed = (r: { stdout: string; stderr: string; code: number }): Result =>
+  r.code === 2
+    ? { ok: false, error: "o omnichat.mjs não reconheceu o pedido (a pasta tem scenes.json ou carousel.json?)" }
+    : { ok: false, error: stripPrefix(joinOutput(r)) || `omnichat.mjs saiu com ${r.code}` };
+
+/* --- where the rule belongs ---------------------------------------------------------------- */
+/* carousel: `id` is the content's slug, and the dir is videos/<slug>/carousel */
+export type RuleTarget = { type: "video" | "post" | "carousel"; id: string; dir: string };
+
+export function videoTarget(slug: string): RuleTarget | null {
+  const dir = videoDirs().get(slug);
+  return dir ? { type: "video", id: slug, dir } : null;
+}
+
+export function carouselTarget(slug: string): RuleTarget | null {
+  const content = videoDirs().get(slug);
+  if (!content) return null;
+  const dir = join(content, "carousel");
+  return existsSync(join(dir, "carousel.json")) ? { type: "carousel", id: slug, dir } : null;
+}
+
+export function postTarget(code: string): RuleTarget | null {
+  if (!CODE_RE.test(code)) return null;
+  const dir = join(POSTS_DIR, code);
+  return existsSync(join(dir, "publication.json")) ? { type: "post", id: code, dir } : null;
+}
+
+/* the CLI only accepts a video dir with scenes.json, a carousel dir with carousel.json (or a
+   post's), and the agent only checks the contents in videos/ (not those in another dir opened with --videos) */
+const real = (p: string) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+};
+function checkTarget(a: RuleTarget): string | null {
+  if (a.type === "post") return null;
+  if (a.type === "carousel") {
+    if (!existsSync(join(a.dir, "carousel.json"))) return "este conteúdo ainda não tem carrossel";
+    if (real(dirname(dirname(a.dir))) !== real(join(ROOT, "videos")))
+      return "o agente do omnichat só confere os conteúdos de videos/ deste projeto";
+    return null;
+  }
+  if (!existsSync(join(a.dir, "scenes.json")))
+    return "este vídeo ainda não tem scenes.json: o omnichat vale depois do roteiro de motion";
+  if (real(dirname(a.dir)) !== real(join(ROOT, "videos")))
+    return "o agente do omnichat só confere os vídeos de videos/ deste projeto";
+  return null;
+}
+
+const ruleOf = (dir: string) =>
+  readJson<{ instagram?: Record<string, unknown> }>(join(dir, "omnichat.json"))?.instagram ?? null;
+const instagramOf = (dir: string) =>
+  readJson<{ instagram?: { id?: string; url?: string; published_at?: string } }>(join(dir, "publication.json"))
+    ?.instagram ?? null;
+const rel = (dir: string) => (relative(ROOT, dir).startsWith("..") ? dir : relative(ROOT, dir));
+
+/* Each `log` pulls the rule's record from the cloud (one request). Every open page rereads every rule on
+   each omnichat notice, so one answer serves for LOG_TTL_MS while the record file stays the same; a
+   change to the file (a pull that brought news, a send, a retry) asks again. Two reads at once share one. */
+const LOG_TTL_MS = 30_000;
+const logCache = new Map<string, { at: number; mtime: number; value: { log: unknown } | { error: string } }>();
+const logReads = new Map<string, Promise<{ log: unknown } | { error: string }>>();
+const recordMtime = (dir: string) => {
+  try {
+    return statSync(join(dir, "omnichat-record.json")).mtimeMs;
+  } catch {
+    return 0;
+  }
+};
+
+async function logOf(dir: string): Promise<{ log: unknown } | { error: string }> {
+  const hit = logCache.get(dir);
+  if (hit && Date.now() - hit.at < LOG_TTL_MS && hit.mtime === recordMtime(dir)) return hit.value;
+  const pending = logReads.get(dir);
+  if (pending) return pending;
+  const read = (async () => {
+    const r = await run([NODE, OMNICHAT, "log", dir, "--json"]);
+    let value: { log: unknown } | { error: string };
+    if (r.code !== 0) value = { error: (failed(r) as { error: string }).error };
+    else {
+      try {
+        value = { log: JSON.parse(r.stdout.trim().split("\n").pop()!) };
+      } catch (e: any) {
+        value = { error: `não deu para ler o log: ${e.message}` };
+      }
+    }
+    logCache.set(dir, { at: Date.now(), mtime: recordMtime(dir), value });
+    return value;
+  })().finally(() => logReads.delete(dir));
+  logReads.set(dir, read);
+  return read;
+}
+
+/* --- status --------------------------------------------------------------------------- */
+/* a token swapped from the terminal (`publish.mjs auth`) changes .env without going through here:
+   a .env newer than the cached read counts as a refresh */
+const ENV_FILE = join(ROOT, ".env");
+const envChanged = (since: number) => {
+  try {
+    return statSync(ENV_FILE).mtimeMs > since;
+  } catch {
+    return false;
+  }
+};
+
+let cachedAccount: { at: number; account: unknown; comments: unknown } | null = null;
+let readingAccount: Promise<void> | null = null;
+
+async function readAccount(refresh: boolean) {
+  if (!refresh && cachedAccount && Date.now() - cachedAccount.at < 2 * 60_000 && !envChanged(cachedAccount.at))
+    return cachedAccount;
+  /* two open pages asking at the same time: only one asks the API */
+  readingAccount ??= (async () => {
+    const r = await run([NODE, OMNICHAT, "status", "--json"]);
+    let s: any;
+    try {
+      s = JSON.parse(r.stdout.trim().split("\n").pop()!);
+    } catch {
+      s = null;
+    }
+    cachedAccount = s
+      ? { at: Date.now(), account: s.account, comments: s.comments }
+      : {
+          at: Date.now(),
+          account: { ready: false, reason: stripPrefix(joinOutput(r)) || `omnichat.mjs saiu com ${r.code}` },
+          comments: null,
+        };
+  })().finally(() => {
+    readingAccount = null;
+  });
+  await readingAccount;
+  return cachedAccount!;
+}
+
+/* the agent and the cloud's health: asked at most once a minute (each ask is a request to the cloud, and
+   every open page rereads this on each omnichat notice) */
+const AGENT_TTL_MS = 60_000;
+let cachedAgent: { at: number; value: any } | null = null;
+let readingAgent: Promise<any> | null = null;
+
+async function agentStatus(refresh = false) {
+  if (!refresh && cachedAgent && Date.now() - cachedAgent.at < AGENT_TTL_MS) return cachedAgent.value;
+  readingAgent ??= (async () => {
+    const r = await run([NODE, OMNICHAT, "agent", "--json"]);
+    let value: any = null;
+    try {
+      value = JSON.parse(r.stdout.trim());
+    } catch {}
+    cachedAgent = { at: Date.now(), value };
+    return value;
+  })().finally(() => {
+    readingAgent = null;
+  });
+  return readingAgent;
+}
+
+/* the whole account's pause (Meta limit or block, token without permission): only holds until `until` */
+function currentPause() {
+  const p = readJson<{ until: string; reason: string; at: string }>(join(OMNICHAT_DIR, "pause.json"));
+  return p && Date.parse(p.until) > Date.now() ? p : null;
+}
+
+/* the same dirs the CLI's `run` goes through: videos/ (and each one's carousel) and .omnichat/posts/ */
+function dirsWithRule(): RuleTarget[] {
+  const targets: RuleTarget[] = [];
+  const names = (d: string) => {
+    try {
+      return readdirSync(d)
+        .filter(n => !n.startsWith("."))
+        .sort();
+    } catch {
+      return [];
+    }
+  };
+  for (const name of names(join(ROOT, "videos"))) {
+    const dir = join(ROOT, "videos", name);
+    if (existsSync(join(dir, "omnichat.json"))) targets.push({ type: "video", id: name, dir });
+    const car = join(dir, "carousel");
+    if (existsSync(join(car, "omnichat.json"))) targets.push({ type: "carousel", id: name, dir: car });
+  }
+  for (const name of names(POSTS_DIR)) {
+    const dir = join(POSTS_DIR, name);
+    if (existsSync(join(dir, "omnichat.json"))) targets.push({ type: "post", id: name, dir });
+  }
+  return targets;
+}
+
+async function ruleSummary(a: RuleTarget) {
+  const r = ruleOf(a.dir);
+  if (!r) return null;
+  const ig = instagramOf(a.dir);
+  const l = await logOf(a.dir);
+  const log = "log" in l ? (l.log as any) : null;
+  return {
+    type: a.type,
+    id: a.id,
+    dir: rel(a.dir),
+    enabled: !!r.enabled,
+    published: !!ig?.id,
+    post: ig?.url ?? null,
+    published_at: ig?.published_at ?? null,
+    keywords: r.any_comment ? null : ((r.keywords as string[] | undefined) ?? []),
+    updated_at: (r.updated_at as string | undefined) ?? null,
+    totals: log?.totals ?? null,
+    checked_at: log?.checked_at ?? null,
+    warning: log?.warning ?? null,
+    log_error: "error" in l ? l.error : null,
+  };
+}
+
+/* a content's Omnichat in one line, for Omni's schedule (get_schedule): is there a rule, is it on, what
+   triggers it, and, before the post goes up, what happens when it does (tools/omnichat.mjs `published`) */
+export function ruleBrief(a: RuleTarget) {
+  const r = ruleOf(a.dir) as {
+    enabled?: boolean;
+    disabled_at?: string;
+    any_comment?: boolean;
+    keywords?: string[];
+  } | null;
+  const brief = {
+    rule: !!r,
+    enabled: !!r?.enabled,
+    keywords: r ? (r.any_comment ? "qualquer comentário" : (r.keywords ?? [])) : null,
+  };
+  if (instagramOf(a.dir)?.id) return brief;
+  const onPublish = r?.enabled
+    ? "ligada: começa a responder quando o post subir"
+    : r?.disabled_at
+      ? "desligada pelo usuário: não liga sozinha"
+      : omnichatConfig().enable_on_publish === true
+        ? "liga sozinha quando o post subir, se a narração pedir o comentário e houver link"
+        : "não liga sozinha: só se o usuário pedir";
+  return { ...brief, on_publish: onPublish };
+}
+
+/* `rules`: the list of all of them (the /omnichat page); without it, only account, agent and pause */
+export async function getOmnichatState(refresh = false, rules = true) {
+  const [c, agent, list] = await Promise.all([
+    readAccount(refresh),
+    agentStatus(refresh),
+    rules ? Promise.all(dirsWithRule().map(ruleSummary)) : Promise.resolve(null),
+  ]);
+  /* while the cloud answers, its pause is the one that holds */
+  const cloud = agent?.cloud;
+  return {
+    agent,
+    pause: cloud?.ready ? (cloud.pause ? { ...cloud.pause, at: "" } : null) : currentPause(),
+    account: c.account,
+    comments: c.comments,
+    checked_at: new Date(c.at).toISOString(),
+    ...(list ? { rules: list.filter(Boolean) } : {}),
+  };
+}
+
+/* the DM and public replies a new rule gets, whether it quotes the Reel, how many comments
+   go out per pass and whether the rule enables itself when the Reel goes up (omnichat.instagram in the config,
+   reread each time: the CLI rereads it too; the defaults are its own) */
+const omnichatConfig = () => readJson<any>(join(ROOT, "omnivideo.config.json"))?.omnichat?.instagram ?? {};
+function buttonDefaults(c: Record<string, unknown>) {
+  const r = resolveOmnichatConfig(c);
+  return {
+    opening_dm: r.default_opening_dm,
+    button_label: r.default_button_label,
+    not_following_dm: r.default_not_following_dm,
+    retry_label: r.default_retry_label,
+    link_label: r.default_link_label,
+    skip_label: r.default_skip_label,
+    skip_dm: r.default_skip_dm,
+  };
+}
+function ruleDefaults() {
+  const c = omnichatConfig();
+  return {
+    dm: typeof c.default_dm === "string" ? c.default_dm : null,
+    public_replies: Array.isArray(c.default_public_replies) ? c.default_public_replies.map(String) : null,
+    max_per_pass: typeof c.max_per_pass === "number" ? c.max_per_pass : null,
+    quote_post: c.quote_post !== false,
+    /* the button texts: the config's, or the core's defaults (the same the CLI falls back to) */
+    ...buttonDefaults(c),
+  };
+}
+
+/* the whole rule (from the file) and the log of a dir */
+export async function getRuleDetail(a: RuleTarget) {
+  const ig = instagramOf(a.dir);
+  const l = await logOf(a.dir);
+  return {
+    type: a.type,
+    id: a.id,
+    dir: rel(a.dir),
+    rule: ruleOf(a.dir),
+    defaults: ruleDefaults(),
+    found_link: a.type !== "post" ? videoLink(a.dir) : null,
+    /* with enable_on_publish, a rule not yet enabled enables when the Reel (or the carousel) goes up
+       (no rule, with the term the narration or the carousel asks for: "comenta REA que eu te mando o link") */
+    on_publish:
+      a.type !== "post" ? { enable: omnichatConfig().enable_on_publish === true, term: narrationKeyword(a.dir) } : null,
+    published: !!ig?.id,
+    post: ig?.url ?? null,
+    published_at: ig?.published_at ?? null,
+    log: "log" in l ? l.log : null,
+    log_error: "error" in l ? l.error : null,
+  };
+}
+
+/* --- saving the rule ------------------------------------------------------------------- */
+const asList = (v: unknown) =>
+  (Array.isArray(v) ? v : typeof v === "string" ? v.split(/[,\n]/) : []).map(s => String(s).trim()).filter(Boolean);
+
+/* only the fields the rule has, with the right type: the rest of the body doesn't reach the CLI */
+function ruleFields(b: any): Record<string, unknown> {
+  const j: Record<string, unknown> = {};
+  if (b?.keywords !== undefined) j.keywords = asList(b.keywords);
+  if (b?.any_comment !== undefined) j.any_comment = b.any_comment === true;
+  if (typeof b?.link === "string") j.link = b.link.trim();
+  if (typeof b?.dm === "string") j.dm = b.dm.trim();
+  /* a public reply may have a comma: one per line */
+  if (b?.public_replies !== undefined)
+    j.public_replies = (Array.isArray(b.public_replies) ? b.public_replies : String(b.public_replies ?? "").split("\n"))
+      .map((s: unknown) => String(s).trim())
+      .filter(Boolean);
+  if (b?.already_replied === "skip" || b?.already_replied === "send") j.already_replied = b.already_replied;
+  if (b?.already_replied_if !== undefined) j.already_replied_if = asList(b.already_replied_if);
+  /* generic requests ("quero", "me manda"…) and what the DM delivers, for Claude to read the context */
+  if (typeof b?.generic_phrases === "boolean") j.generic_phrases = b.generic_phrases;
+  if (typeof b?.offer === "string") j.offer = b.offer.trim();
+  /* the Reel link on the DM's first line, so it reads as a reply to it */
+  if (typeof b?.quote_post === "boolean") j.quote_post = b.quote_post;
+  /* the button and the follow gate */
+  if (typeof b?.button === "boolean") j.button = b.button;
+  if (typeof b?.require_follow === "boolean") j.require_follow = b.require_follow;
+  /* the link in a button that opens it */
+  if (typeof b?.link_button === "boolean") j.link_button = b.link_button;
+  if (typeof b?.follow_skip === "boolean") j.follow_skip = b.follow_skip;
+  for (const k of [
+    "opening_dm",
+    "button_label",
+    "not_following_dm",
+    "retry_label",
+    "link_label",
+    "skip_label",
+    "skip_dm",
+  ])
+    if (typeof b?.[k] === "string") j[k] = b[k].trim();
+  return j;
+}
+
+const saving = new Set<string>();
+
+export async function saveRule(
+  a: RuleTarget,
+  body: unknown,
+): Promise<Result & { rule?: unknown; problems?: string[] }> {
+  const e = checkTarget(a);
+  if (e) return { ok: false, error: e };
+  if (saving.has(a.dir)) return { ok: false, error: "a regra deste vídeo já está sendo gravada" };
+  saving.add(a.dir);
+  try {
+    const r = await run([NODE, OMNICHAT, "rule", a.dir, "--json", JSON.stringify(ruleFields(body))]);
+    if (r.code !== 0) return failed(r);
+    const j = JSON.parse(r.stdout.trim().split("\n").pop()!);
+    const problems: string[] = j.problems ?? [];
+    const output = problems.length
+      ? "regra gravada, desligada: veja acima o que falta para ligar"
+      : j.rule?.enabled
+        ? "regra gravada: vale a partir da próxima passada"
+        : "regra gravada";
+    return { ok: true, output, rule: j.rule, problems };
+  } catch (e: any) {
+    return { ok: false, error: `não deu para ler a resposta do omnichat.mjs: ${e.message}` };
+  } finally {
+    saving.delete(a.dir);
+  }
+}
+
+/* A post already live (Reel, carousel or photo): `post` finds the media by link among the account's
+   posts and creates .omnichat/posts/<code>/ (or uses the video or carousel dir, if the post came from
+   omnivideo). Prints "<Reel|carrossel|foto|post> <permalink> → <dir>" and the rule's JSON on the last line. */
+export async function createRuleFromLink(
+  body: any,
+): Promise<Result & { type?: RuleTarget["type"]; id?: string; problems?: string[] }> {
+  const link = String(body?.link ?? "").trim();
+  if (!/^https?:\/\/(www\.)?instagram\.com\/\S+$/.test(link) && !/^\d{5,}$/.test(link))
+    return {
+      ok: false,
+      error:
+        "cole o link do post, como https://www.instagram.com/p/…/ (carrossel ou foto) ou https://www.instagram.com/reel/…/",
+    };
+  /* the body's `link` is the post's: what the DM delivers is left for the rule panel */
+  const { link: _post, ...rule } = body ?? {};
+  const r = await run([NODE, OMNICHAT, "post", link, "--json", JSON.stringify(ruleFields(rule))]);
+  if (r.code !== 0) return failed(r);
+  const lines = r.stdout.trim().split("\n");
+  const dest = /→ (.+)$/.exec(lines[0] ?? "")?.[1]?.trim() ?? "";
+  const m = /(?:^|\/)\.omnichat\/posts\/([\w-]+)$/.exec(dest);
+  const carousel = !m && basename(dest) === "carousel";
+  const video = m ? null : basename(carousel ? dirname(dest) : dest);
+  let problems: string[] = [];
+  try {
+    problems = JSON.parse(lines.at(-1)!).problems ?? [];
+  } catch {
+    /* the rule was saved; the UI rereads the rest */
+  }
+  return {
+    ok: true,
+    output: lines[0] ?? "regra criada",
+    type: m ? "post" : carousel ? "carousel" : "video",
+    id: m?.[1] ?? video!,
+    problems,
+  };
+}
+
+/* --- enable, disable, retry, dry run -------------------------------------------------- */
+/* enabling means replying outward, on behalf of the account: the Omnichat page only gets here with the
+   confirmation; the Publish stage enables through the term (enableRuleWithTerm). Disabling also works with no
+   rule enabled: it records "don't enable by yourself when the Reel goes up" */
+export async function enableRule(a: RuleTarget, enable: unknown): Promise<Result> {
+  if (typeof enable !== "boolean") return { ok: false, error: "enable: true ou false" };
+  const e = checkTarget(a);
+  if (e) return { ok: false, error: e };
+  const r = await run([NODE, OMNICHAT, enable ? "enable" : "disable", a.dir, ...(enable ? ["--confirm"] : [])]);
+  return r.code === 0 ? { ok: true, output: joinOutput(r) } : failed(r);
+}
+
+/* The Publish stage asks only for the term, and saving the term already enables, no second click: writing the
+   term is the authorization, by the user's decision. Without a rule, it is born with the config defaults
+   (the CLI adds the DM and the public replies), generic requests on and the link found in the video.
+   With a disabled rule, only the term changes, and the link only goes in if it has none: link, DM, replies
+   and already-replied stay as the Omnichat page left them. A rule that doesn't add up (without the link
+   the DM uses) stays saved, disabled, and the response says what's missing. */
+export async function enableRuleWithTerm(a: RuleTarget, term: unknown): Promise<Result & { problems?: string[] }> {
+  const e = checkTarget(a);
+  if (e) return { ok: false, error: e };
+  const keywords = asList(typeof term === "string" ? term : "");
+  if (!keywords.length) return { ok: false, error: "escreva o termo que a pessoa comenta, como QUERO" };
+  if (saving.has(a.dir)) return { ok: false, error: "a regra deste vídeo já está sendo gravada" };
+  saving.add(a.dir);
+  try {
+    const before = ruleOf(a.dir) as {
+      enabled?: boolean;
+      any_comment?: boolean;
+      keywords?: string[];
+      link?: string;
+    } | null;
+    if (before?.enabled) return { ok: false, error: "a regra já está ligada: troque o termo na página do Omnichat" };
+    if (before?.any_comment)
+      return { ok: false, error: "esta regra dispara com qualquer comentário: ligue pela página do Omnichat" };
+    const j: Record<string, unknown> = {};
+    if (!before) Object.assign(j, { keywords, any_comment: false, generic_phrases: true });
+    else if (JSON.stringify(before.keywords ?? []) !== JSON.stringify(keywords)) j.keywords = keywords;
+    const found = a.type !== "post" ? videoLink(a.dir) : null;
+    if (!before?.link && found) j.link = found.link;
+    if (Object.keys(j).length) {
+      const r = await run([NODE, OMNICHAT, "rule", a.dir, "--json", JSON.stringify(j)]);
+      if (r.code !== 0) return failed(r);
+      const problems: string[] = JSON.parse(r.stdout.trim().split("\n").pop()!).problems ?? [];
+      if (problems.length)
+        return {
+          ok: false,
+          error: `o termo ficou gravado, mas a regra não liga ainda:\n${problems.join("\n")}`,
+          problems,
+        };
+    }
+    const r = await run([NODE, OMNICHAT, "enable", a.dir, "--confirm"]);
+    return r.code === 0 ? { ok: true, output: joinOutput(r) } : failed(r);
+  } catch (e: any) {
+    return { ok: false, error: `não deu para ler a resposta do omnichat.mjs: ${e.message}` };
+  } finally {
+    saving.delete(a.dir);
+  }
+}
+
+/* what failed without the DM goes back to the queue (within the 7 days) */
+export async function retryFailed(a: RuleTarget): Promise<Result> {
+  const e = checkTarget(a);
+  if (e) return { ok: false, error: e };
+  const r = await run([NODE, OMNICHAT, "retry", a.dir]);
+  return r.code === 0 ? { ok: true, output: joinOutput(r) } : failed(r);
+}
+
+/* reads the comments and shows what it would send, without sending or saving anything; one per dir */
+const dryRunning = new Set<string>();
+export async function dryRunRule(a: RuleTarget): Promise<Result> {
+  const e = checkTarget(a);
+  if (e) return { ok: false, error: e };
+  if (dryRunning.has(a.dir)) return { ok: false, error: "a simulação deste vídeo já está rodando" };
+  dryRunning.add(a.dir);
+  try {
+    const r = await run([NODE, OMNICHAT, "run", a.dir, "--dry-run"]);
+    return r.code === 0 ? { ok: true, output: joinOutput(r) || "nada para mostrar" } : failed(r);
+  } finally {
+    dryRunning.delete(a.dir);
+  }
+}
+
+/* --- by hand: who got no DM, and the chosen send -------------------------------------
+   `comments --json` reads the Reel now (seconds) and returns who didn't get the DM; read only.
+   `send` sends the rule's DM to the chosen ones: the UI only gets here with the confirmation in two
+   clicks (in bulk) or with the written reply and the Reply of a focused comment, and
+   --confirm is it. `text` is the comment reply written on the UI, in place of
+   the rule's random ones; `public_reply_only` replies only on the comment, without the DM. One of each per dir. */
+const readingComments = new Set<string>();
+export async function listMissingDms(a: RuleTarget): Promise<Result & { list?: unknown }> {
+  const e = checkTarget(a);
+  if (e) return { ok: false, error: e };
+  if (readingComments.has(a.dir)) return { ok: false, error: "os comentários deste vídeo já estão sendo lidos" };
+  readingComments.add(a.dir);
+  try {
+    const r = await run([NODE, OMNICHAT, "comments", a.dir, "--json"]);
+    if (r.code !== 0) return failed(r);
+    return { ok: true, output: "", list: JSON.parse(r.stdout.trim().split("\n").pop()!) };
+  } catch (e: any) {
+    return { ok: false, error: `não deu para ler a resposta do omnichat.mjs: ${e.message}` };
+  } finally {
+    readingComments.delete(a.dir);
+  }
+}
+
+const sending = new Set<string>();
+export async function sendManual(a: RuleTarget, body: any): Promise<Result & { sent?: number; results?: unknown }> {
+  const e = checkTarget(a);
+  if (e) return { ok: false, error: e };
+  const ids: string[] = Array.isArray(body?.ids) ? body.ids.map(String) : [];
+  if (!ids.length || ids.length > 500 || ids.some(i => !/^\d{1,30}$/.test(i)))
+    return { ok: false, error: "escolha os comentários" };
+  const publicOnly = body?.public_reply_only === true;
+  const text = typeof body?.text === "string" ? body.text.trim() : "";
+  if (text.startsWith("--")) return { ok: false, error: "a resposta no comentário não pode começar com --" };
+  if (text.length > 2200) return { ok: false, error: "a resposta no comentário passa de 2.200 caracteres" };
+  if (publicOnly && !text) return { ok: false, error: "sem a DM, escreva a resposta no comentário" };
+  if (sending.has(a.dir)) return { ok: false, error: "já estou mandando as respostas deste vídeo" };
+  sending.add(a.dir);
+  try {
+    const publicFlags = publicOnly
+      ? ["--public-reply-only", "--public-reply", text]
+      : body?.public_reply === false
+        ? ["--no-public-reply"]
+        : text
+          ? ["--public-reply", text]
+          : [];
+    const r = await run([NODE, OMNICHAT, "send", a.dir, ...ids, "--confirm", "--json", ...publicFlags]);
+    if (r.code !== 0) return failed(r);
+    const j = JSON.parse(r.stdout.trim().split("\n").pop()!);
+    return {
+      ok: true,
+      output: `${j.sent} de ${ids.length} ${publicOnly ? "respondidos no comentário" : "com a DM entregue"}`,
+      sent: j.sent,
+      results: j.results,
+    };
+  } catch (e: any) {
+    return { ok: false, error: `não deu para ler a resposta do omnichat.mjs: ${e.message}` };
+  } finally {
+    sending.delete(a.dir);
+  }
+}
+
+/* Apagar: deletes comments on Instagram (a person's or the account's own reply), no way back. The UI asks
+   for a second click first; `delete --confirm` is that. One per dir. */
+const deleting = new Set<string>();
+export async function deleteComments(
+  a: RuleTarget,
+  ids: string[],
+): Promise<Result & { deleted?: number; results?: unknown }> {
+  const e = checkTarget(a);
+  if (e) return { ok: false, error: e };
+  if (!ids.length || ids.length > 50 || ids.some(i => !/^\d{1,30}$/.test(i)))
+    return { ok: false, error: "escolha os comentários" };
+  if (deleting.has(a.dir)) return { ok: false, error: "já estou apagando comentários deste vídeo" };
+  deleting.add(a.dir);
+  try {
+    const r = await run([NODE, OMNICHAT, "delete", a.dir, ...ids, "--confirm", "--json"]);
+    if (r.code !== 0) return failed(r);
+    const j = JSON.parse(r.stdout.trim().split("\n").pop()!);
+    if (!j.deleted) return { ok: false, error: j.results?.[0]?.reason ?? "não deu para apagar" };
+    return { ok: true, output: `${j.deleted} de ${ids.length} apagados`, deleted: j.deleted, results: j.results };
+  } catch (e: any) {
+    return { ok: false, error: `não deu para ler a resposta do omnichat.mjs: ${e.message}` };
+  } finally {
+    deleting.delete(a.dir);
+  }
+}
+
+/* enables and disables the launchd agent: installs with the studio's node */
+export async function setOmnichatAgent(enable: unknown): Promise<Result> {
+  if (typeof enable !== "boolean") return { ok: false, error: "enable: true ou false" };
+  const r = await run([NODE, OMNICHAT, "agent", enable ? "install" : "uninstall"]);
+  cachedAgent = null;
+  return r.code === 0 ? { ok: true, output: joinOutput(r) } : failed(r);
+}