Open source CapCut alternative.
TypeScript
// 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");
}