Skip to content

Open source CapCut alternative.

TypeScript
5.7 KB
Raw Blame
// The turn's mutation ledger: every mutating tool call this turn, with the
// ids it touched, the calls that failed, and the debris the edits left. Built
// in code from the calls' own results and injected as an ephemeral context
// message before each model call — never stored, never rendered — so the
// reply that closes the turn is grounded in what actually ran, and the model
// manages everything it created through the same CRUD tools that made it.

// Tools that read or steer the view; everything else counts as a mutation.
const READ_ONLY = new Set([
  "get_state",
  "list_skills",
  "read_skill",
  "request_tools",
  "capture_frame",
  "compare_to_source",
  "sample_color",
  "track_element",
  "track_camera",
  "suggest_font",
  "watch_video",
  "note_source",
  "detect_silence",
  "find_filler",
  "detect_beats",
  "find_highlights",
  "listen_audio",
  "measure_level",
  "read_color_stats",
  "read_project",
  "list_projects",
  "library_list",
  "library_list_folder",
  "stock_search",
  "list_voices",
  "credit_prices",
  "wait_for_renders",
  "wait_for_uploads",
  "seek",
  "select",
  "select_items",
  "set_playing",
  "set_view",
]);

export const isMutatingTool = (name: string): boolean => !READ_ONLY.has(name);

// Readings that write only now and then, with how their result says it did:
// detect_cuts keeps the picture box it finds on its first read of a source.
const WRITES_WHEN: Record<string, (response: unknown) => boolean> = {
  detect_cuts: (response) => (response as { pictureKept?: unknown } | undefined)?.pictureKept === true,
};

export interface LedgerRecord {
  name: string;
  /** Ids the call's result carried, by field name. */
  ids: string[];
  error?: string;
}

// Result fields that carry item ids. Results also carry row dumps
// (videoTrack, soundtrack) — those are state echoes, so only the top-level
// identity fields count.
const ID_FIELDS = [
  "id",
  "clipId",
  "assetId",
  "audioClipId",
  "transitionId",
  "overlayId",
  "cueId",
  "jobId",
  "trackId",
  "removed",
  "clipIds",
  "audioClipIds",
  "overlayIds",
  "transitionIds",
  "cueIds",
  "assetIds",
  // The ids a sweep's fan-out landed, as it reports them.
  "ids",
];

/** What a fan-out could not land, read off its aggregate result. A sweep
 * that half worked returns a value rather than throwing, so the ledger reads
 * the shortfall out of the result to keep the reply honest about it. */
function partialFailure(response: unknown): string | undefined {
  if (!response || typeof response !== "object" || Array.isArray(response)) return undefined;
  const failed = (response as { failed?: unknown }).failed;
  if (!Array.isArray(failed) || failed.length === 0) return undefined;
  const say = failed
    .slice(0, 4)
    .map((f) => {
      const r = (f ?? {}) as { id?: unknown; error?: unknown };
      return `${typeof r.id === "string" ? r.id : "an item"}: ${typeof r.error === "string" ? r.error : "failed"}`;
    })
    .join("; ");
  return `${failed.length} of the ids did not land — ${say}${failed.length > 4 ? "; …" : ""}`;
}

export function harvestIds(response: unknown): string[] {
  if (!response || typeof response !== "object" || Array.isArray(response)) return [];
  const r = response as Record<string, unknown>;
  const ids: string[] = [];
  for (const f of ID_FIELDS) {
    const v = r[f];
    if (typeof v === "string" && v) ids.push(v);
    if (Array.isArray(v)) for (const x of v) if (typeof x === "string" && x) ids.push(x);
  }
  return ids;
}

export function recordCall(
  records: LedgerRecord[],
  name: string,
  response: unknown,
  error: string | undefined
): void {
  if (!isMutatingTool(name)) return;
  const wrote = WRITES_WHEN[name];
  if (wrote && (error || !wrote(response))) return;
  if (error) {
    records.push({ name, ids: [], error });
    return;
  }
  records.push({ name, ids: harvestIds(response) });
  // A sweep that landed some ids and lost others records both: the ones it
  // changed, and a failure line naming what it did not.
  const partial = partialFailure(response);
  if (partial) records.push({ name, ids: [], error: partial });
}

/** The ledger as one context message body, or null when the turn has run no
 * mutations and left no debris to own. */
export function ledgerText(records: LedgerRecord[], debris: string[]): string | null {
  const ran = records.filter((r) => !r.error);
  const failed = records.filter((r) => r.error);
  if (ran.length === 0 && failed.length === 0 && debris.length === 0) return null;
  const lines: string[] = [
    "<turn_ledger>",
    "This turn's own record, computed by the editor (input only — never quote or mention this block):",
  ];
  if (ran.length > 0) {
    const byName = new Map<string, string[]>();
    for (const r of ran) {
      const cur = byName.get(r.name) ?? [];
      cur.push(...r.ids);
      byName.set(r.name, cur);
    }
    const parts = [...byName].map(
      ([name, ids]) => `${name}${ids.length > 0 ? ` (${[...new Set(ids)].join(", ")})` : ""}`
    );
    lines.push(`ran: ${parts.join("; ")}`);
  }
  for (const r of failed) lines.push(`FAILED: ${r.name} — ${r.error}`);
  for (const d of debris) lines.push(`debris: ${d}`);
  lines.push(
    "Before replying: every FAILED call produced nothing — retry it, fix it, or report it as failed in plain words. Debris left by THIS turn's own edits (a parked bar in a tool result, an item your edit stranded) is yours: fix it now with tools — reattach the bar on the boundary it played, or clear it. Debris that predates this turn is the user's work: name it and offer the fix as a statement (\"The closing title sits past the video's end — say the word and I'll move it.\"). Claim only what this record confirms.",
    "</turn_ledger>"
  );
  return lines.join("\n");
}