Skip to content

Open source CapCut alternative.

TypeScript
9.9 KB
Raw Blame
// A batch of editor commands as a durable job. A host with its own
// conversation — the ChatGPT app — sends typed tool calls with no model of
// ours in the loop. The editor open in the ChatGPT card claims the batch,
// runs it on the document in front of the user through the same executors
// the chat uses, saves, and reports back. Nothing else runs a batch: one no
// card claims in time is dismissed, and the tool call says the project has to
// be open in the card.
import type { Prisma } from "@/generated/prisma/client";
import { prisma } from "@/lib/prisma";
import type { CommandJobResult, CommandJobSpec, CommandOutcome } from "@/cut/lib/commandBatch";
import { needsWorker } from "./jobs";
import { liveJobCheck } from "./limits";
import { queueLeasedJob } from "./lease";
import { getProject } from "./projects";
import { err } from "./util";
import { wakeRenderWorker } from "./wake";

export type { CommandCall, CommandJobResult, CommandJobSpec, CommandOutcome } from "@/cut/lib/commandBatch";

export const MAX_COMMANDS_PER_BATCH = 40;

/** How long a claimed batch may go without a heartbeat before the editor
 * that claimed it counts as gone. The card beats every ten seconds. */
export const CLAIM_QUIET_MS = 30_000;

/** The answer a tool call gets when nothing claimed its batch. */
export const NO_CARD_OPEN = "No Donkey Cut card has this project open in the chat. Call open_project, then try again.";

export type JobRow = NonNullable<Awaited<ReturnType<typeof prisma.cutRenderJob.findFirst>>>;

const specOf = (row: Pick<JobRow, "spec">) => (row.spec ?? {}) as unknown as CommandJobSpec;
const specJson = (spec: CommandJobSpec) => spec as unknown as Prisma.InputJsonValue;
const resultJson = (result: CommandJobResult) => result as unknown as Prisma.InputJsonValue;

/** Batches whose editor stopped beating end here, so they never hold the
 * project's lease or a job slot. Runs on every queue and claim. */
async function expireQuietBatches(userId: string, projectId: string): Promise<void> {
  await prisma.cutRenderJob.updateMany({
    where: { userId, projectId, kind: "commands", state: "running", updatedAt: { lt: new Date(Date.now() - CLAIM_QUIET_MS) } },
    data: { state: "error", error: "The editor in the card stopped responding." },
  });
}

export async function queueCommands(
  userId: string,
  projectId: string,
  spec: CommandJobSpec
): Promise<{ id: string } | Response> {
  if (!(await getProject(userId, projectId))) return err("Project not found.", 404);
  if (!Array.isArray(spec.commands) || spec.commands.length === 0) return err("At least one command is required.", 400);
  if (spec.commands.length > MAX_COMMANDS_PER_BATCH) return err(`At most ${MAX_COMMANDS_PER_BATCH} commands per batch.`, 400);
  await expireQuietBatches(userId, projectId);
  const capped = await liveJobCheck(userId);
  if (capped) return capped;
  if (spec.readOnly) {
    // A read never saves, so it runs beside whatever holds the write lease.
    const row = await prisma.cutRenderJob.create({ data: { userId, projectId, kind: "commands", spec: specJson(spec) } });
    return { id: row.id };
  }
  // The card runs batches one after another, so they queue behind each
  // other and contend only with a chat turn editing the same document.
  return queueLeasedJob(userId, projectId, "commands", specJson(spec), { wake: false, contendsWith: ["agent_turn"] });
}

const TERMINAL = new Set(["done", "error", "canceled", "dismissed"]);

/** A queued batch older than the claim window: no card picked it up. The
 * window is measured from the row's age, the one clock the card's polling
 * and this wait share. */
const claimWindowClosed = (row: Pick<JobRow, "createdAt">, claimMs: number) =>
  Date.now() - row.createdAt.getTime() > claimMs;

async function dismissBatch(row: Pick<JobRow, "id">): Promise<void> {
  await prisma.cutRenderJob.updateMany({
    where: { id: row.id, state: "queued" },
    data: { state: "dismissed", error: NO_CARD_OPEN },
  });
}

async function expireBatch(row: Pick<JobRow, "id">): Promise<void> {
  await prisma.cutRenderJob.updateMany({
    where: { id: row.id, state: "running" },
    data: { state: "error", error: "The editor in the card stopped responding." },
  });
}

/** Poll a job row until it settles or the budget runs out. The row comes back
 * either way; the caller reads its state. A command batch no card claims
 * within `editorClaimMs` is dismissed, unless `editorBootDeadline` says a
 * card is still booting its editor; one whose editor stops beating ends in
 * error. Any other kind of job is the worker's, which is woken as needed. */
export async function waitForJob(
  userId: string,
  jobId: string,
  budgetMs: number,
  opts: { editorClaimMs?: number; editorBootDeadline?: () => Promise<number> } = {}
): Promise<JobRow | null> {
  const deadline = Date.now() + budgetMs;
  const claimMs = opts.editorClaimMs ?? 3000;
  for (;;) {
    const row = await prisma.cutRenderJob.findFirst({ where: { id: jobId, userId } });
    if (!row) return null;
    if (TERMINAL.has(row.state)) return row;
    if (row.kind === "commands") {
      // A card that framed a moment ago claims once its editor boots.
      const booting = row.state === "queued" && opts.editorBootDeadline && Date.now() < (await opts.editorBootDeadline());
      if (row.state === "queued" && claimWindowClosed(row, claimMs) && !booting) {
        await dismissBatch(row);
        continue;
      }
      if (row.state === "running" && Date.now() - row.updatedAt.getTime() > CLAIM_QUIET_MS) {
        await expireBatch(row);
        continue;
      }
    } else if (needsWorker(row)) {
      wakeRenderWorker();
    }
    if (Date.now() >= deadline) return row;
    await new Promise((r) => setTimeout(r, Math.min(1000, Math.max(50, deadline - Date.now()))));
  }
}

/** The editor in the card asks for the project's oldest waiting batch. */
export async function claimEditorBatch(
  userId: string,
  projectId: string
): Promise<{ id: string; spec: CommandJobSpec } | null> {
  await expireQuietBatches(userId, projectId);
  const candidates = await prisma.cutRenderJob.findMany({
    where: { userId, projectId, kind: "commands", state: "queued" },
    orderBy: [{ createdAt: "asc" }, { id: "asc" }],
    select: { id: true, spec: true },
    take: 5,
  });
  for (const row of candidates) {
    const { count } = await prisma.cutRenderJob.updateMany({
      where: { id: row.id, state: "queued" },
      data: { state: "running", claimedAt: new Date(), progress: 0, error: null },
    });
    if (count === 1) return { id: row.id, spec: specOf(row) };
  }
  return null;
}

/** The editor keeps a claimed batch alive while it runs. False once the batch
 * is no longer running — expired, canceled — so the editor stops. */
export async function heartbeatEditorBatch(userId: string, jobId: string, progress: number | null): Promise<boolean> {
  const { count } = await prisma.cutRenderJob.updateMany({
    where: { id: jobId, userId, kind: "commands", state: "running" },
    data: { updatedAt: new Date(), ...(progress !== null ? { progress: Math.max(0, Math.min(1, progress)) } : {}) },
  });
  return count === 1;
}

export type EditorReport =
  | { ok: true; results: CommandOutcome[]; changed: boolean; docVersion: string | null }
  | { ok: false; error: string };

/** The editor reports a batch it ran. False when the batch is no longer
 * running, so a late report after an expiry changes nothing. */
export async function settleEditorBatch(userId: string, jobId: string, report: EditorReport): Promise<boolean> {
  const row = await prisma.cutRenderJob.findFirst({
    where: { id: jobId, userId, kind: "commands", state: "running" },
    select: { spec: true },
  });
  if (!row) return false;
  const data = report.ok
    ? {
        state: "done",
        progress: 1,
        result: resultJson({
          results: report.results,
          changed: report.changed && !specOf(row).readOnly,
          docVersion: report.changed ? report.docVersion : null,
        }),
      }
    : { state: "error", error: report.error.slice(0, 2000) };
  const { count } = await prisma.cutRenderJob.updateMany({ where: { id: jobId, state: "running" }, data });
  return count === 1;
}

const isOutcome = (r: unknown): r is CommandOutcome =>
  Boolean(r) && typeof r === "object" && typeof (r as CommandOutcome).name === "string" && typeof (r as CommandOutcome).ok === "boolean";

/** The editor's report, read out of the request body. */
function parseReport(body: unknown): EditorReport | null {
  if (!body || typeof body !== "object") return null;
  const b = body as { ok?: unknown; results?: unknown; changed?: unknown; docVersion?: unknown; error?: unknown };
  if (b.ok === false) return { ok: false, error: typeof b.error === "string" ? b.error : "The editor could not run the batch." };
  if (!Array.isArray(b.results)) return null;
  return {
    ok: true,
    results: b.results.filter(isOutcome),
    changed: b.changed === true,
    docVersion: typeof b.docVersion === "string" ? b.docVersion : null,
  };
}

/** The routes the editor in the card uses to run batches. */
export const commandsCloud = {
  async claim(userId: string, projectId: string) {
    const claimed = await claimEditorBatch(userId, projectId);
    if (!claimed) return new Response(null, { status: 204 });
    return Response.json(claimed);
  },
  async heartbeat(userId: string, jobId: string, req: Request) {
    const body = (await req.json().catch(() => ({}))) as { progress?: unknown };
    const alive = await heartbeatEditorBatch(userId, jobId, typeof body.progress === "number" ? body.progress : null);
    return alive ? Response.json({ ok: true }) : err("Not a running batch.", 409);
  },
  async result(userId: string, jobId: string, req: Request) {
    const report = parseReport(await req.json().catch(() => null));
    if (!report) return err("Bad result.", 400);
    const settled = await settleEditorBatch(userId, jobId, report);
    return settled ? Response.json({ ok: true }) : err("Not a running batch.", 409);
  },
};