Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { appendFileSync } from "node:fs";
import { extname, isAbsolute, resolve } from "node:path";
const TOOL_CONTEXT_VERSION = 1;
export interface ToolContext {
events?: { path: string };
projectLock?: { waitMs: number };
}
export type ArtifactRole = "contact-sheet" | "frame" | "finding" | "check-report";
interface ArtifactCreatedEvent {
version: typeof TOOL_CONTEXT_VERSION;
type: "artifact.created";
command: string;
artifact: { role: ArtifactRole; path: string; mediaType: string };
}
const isRecord = (value: unknown): value is Record<string, unknown> =>
typeof value === "object" && value !== null && !Array.isArray(value);
function parseEvents(value: unknown): ToolContext["events"] {
if (!isRecord(value) || !isRecord(value.transport)) return undefined;
const { type, path } = value.transport;
if (type !== "ndjson-file" || typeof path !== "string" || !isAbsolute(path)) return undefined;
return { path };
}
function parseProjectLock(value: unknown): ToolContext["projectLock"] {
if (!isRecord(value)) return undefined;
const { waitMs } = value;
if (typeof waitMs !== "number" || !Number.isFinite(waitMs) || waitMs < 0) return undefined;
return { waitMs };
}
export function readToolContext(raw = process.env.HF_TOOL_CONTEXT): ToolContext {
if (!raw) return {};
let value: unknown;
try {
value = JSON.parse(raw);
} catch {
return {};
}
if (!isRecord(value) || value.version !== TOOL_CONTEXT_VERSION || !isRecord(value.capabilities))
return {};
const events = parseEvents(value.capabilities.events);
const projectLock = parseProjectLock(value.capabilities["project-lock"]);
return { ...(events && { events }), ...(projectLock && { projectLock }) };
}
const MEDIA_TYPES: Record<string, string> = {
".png": "image/png",
".jpg": "image/jpeg",
".jpeg": "image/jpeg",
".json": "application/json",
};
export function reportArtifacts(
command: string,
role: ArtifactRole,
paths: readonly string[],
context = readToolContext(),
): void {
if (!context.events || paths.length === 0) return;
const lines = paths.map((path) => {
const absolute = resolve(path);
const event: ArtifactCreatedEvent = {
version: TOOL_CONTEXT_VERSION,
type: "artifact.created",
command,
artifact: {
role,
path: absolute,
mediaType: MEDIA_TYPES[extname(absolute).toLowerCase()] ?? "application/octet-stream",
},
};
return JSON.stringify(event) + "\n";
});
try {
appendFileSync(context.events.path, lines.join(""));
} catch (error) {
console.error(`HF_TOOL_CONTEXT events could not be written: ${(error as Error).message}`);
}
}