@remixmate/cli 0.1.0

package/dist/handlers/index.js

@@ -0,0 +1,14 @@
+/**
+ * Handler registry — maps `entry.handler` strings to their implementation.
+ *
+ * Only `entry.type` in ('http' | 'builtin') uses this registry; python
+ * skills go through spawn() in runner.ts and bypass handlers entirely.
+ */
+import { genImage } from './gen-image.js';
+import { genVoice } from './gen-voice.js';
+import { templateBind } from './template-bind.js';
+export const HANDLERS = {
+    'gen-image': genImage,
+    'gen-voice': genVoice,
+    'template-bind': templateBind,
+};

package/dist/handlers/template-bind.d.ts

@@ -0,0 +1,15 @@
+/**
+ * template-bind handler — list available video templates.
+ *
+ * The DSL → TemplateBinding logic is intentionally NOT exposed via the CLI;
+ * it stays inside `skills/template-bind/scripts/match_template.py` and is
+ * imported in-process by `render-video`. The skill's only CLI surface is
+ * `--list-templates`, which we re-implement in TS here.
+ *
+ * Registry resolution (mirrors skills/template-bind/scripts/registry_loader.py):
+ *   1. VIDEO_TEMPLATE_REGISTRY            — explicit local file
+ *   2. VIDEO_TEMPLATE_REGISTRY_URL        — HTTP API (POST by default, with X-Priv-Token)
+ *   3. <repo>/template-library/packages/metadata/registry.json  — monorepo dev fallback
+ */
+import type { HandlerContext, HandlerInput } from './index.js';
+export declare function templateBind(input: HandlerInput, _ctx: HandlerContext): Promise<void>;

package/dist/handlers/template-bind.js

@@ -0,0 +1,149 @@
+/**
+ * template-bind handler — list available video templates.
+ *
+ * The DSL → TemplateBinding logic is intentionally NOT exposed via the CLI;
+ * it stays inside `skills/template-bind/scripts/match_template.py` and is
+ * imported in-process by `render-video`. The skill's only CLI surface is
+ * `--list-templates`, which we re-implement in TS here.
+ *
+ * Registry resolution (mirrors skills/template-bind/scripts/registry_loader.py):
+ *   1. VIDEO_TEMPLATE_REGISTRY            — explicit local file
+ *   2. VIDEO_TEMPLATE_REGISTRY_URL        — HTTP API (POST by default, with X-Priv-Token)
+ *   3. <repo>/template-library/packages/metadata/registry.json  — monorepo dev fallback
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SkillError } from '../http.js';
+const __filename = fileURLToPath(import.meta.url);
+function monorepoFallbackPath() {
+    // <ab-skill>/dist/handlers/ → up 4 → repo root
+    const here = path.dirname(__filename);
+    return path.resolve(here, '..', '..', '..', '..', 'template-library', 'packages', 'metadata', 'registry.json');
+}
+function loadFromFile(filePath) {
+    const raw = readFileSync(filePath, 'utf-8');
+    return JSON.parse(raw);
+}
+async function loadFromHttp(url) {
+    const method = (process.env.VIDEO_TEMPLATE_REGISTRY_HTTP_METHOD ?? 'POST').toUpperCase();
+    const headers = { Accept: 'application/json' };
+    if (method === 'POST')
+        headers['Content-Type'] = 'application/json';
+    const token = (process.env.PRIV_TOKEN ?? '').trim();
+    if (token)
+        headers['X-Priv-Token'] = token;
+    const body = method === 'POST' ? '{}' : undefined;
+    const resp = await fetch(url, { method, headers, body });
+    if (!resp.ok) {
+        throw new SkillError(`registry HTTP failed: ${resp.status} ${await resp.text()}`);
+    }
+    const parsed = (await resp.json());
+    if ('code' in parsed && 'data' in parsed) {
+        if (parsed.code !== 0 && parsed.code !== '0') {
+            throw new SkillError(`registry HTTP business error: code=${parsed.code} msg=${parsed.msg ?? ''}`);
+        }
+        return parsed.data;
+    }
+    return parsed;
+}
+async function loadRegistry() {
+    const explicit = (process.env.VIDEO_TEMPLATE_REGISTRY ?? '').trim();
+    if (explicit) {
+        process.stderr.write(`[template-bind] using explicit file: ${explicit}\n`);
+        return loadFromFile(explicit);
+    }
+    const url = (process.env.VIDEO_TEMPLATE_REGISTRY_URL ?? '').trim();
+    if (url) {
+        process.stderr.write(`[template-bind] using HTTP registry: ${url}\n`);
+        return loadFromHttp(url);
+    }
+    const fallback = monorepoFallbackPath();
+    if (existsSync(fallback)) {
+        process.stderr.write(`[template-bind] using monorepo registry (fallback): ${fallback}\n`);
+        return loadFromFile(fallback);
+    }
+    throw new SkillError('template registry not found. Set VIDEO_TEMPLATE_REGISTRY (local file) or VIDEO_TEMPLATE_REGISTRY_URL (HTTP API).');
+}
+function statusOf(tpl) {
+    const raw = (tpl.status ?? '').trim().toLowerCase();
+    return raw || 'stable';
+}
+function isTruthyEnv(name) {
+    const v = (process.env[name] ?? '').trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+function visibleStatuses() {
+    const allowed = new Set(['stable']);
+    if (isTruthyEnv('ENABLE_BETA_TEMPLATES'))
+        allowed.add('beta');
+    return allowed;
+}
+function matchesFilter(tpl, opts) {
+    if (opts.tag) {
+        const needle = opts.tag.toLowerCase();
+        const tags = (tpl.styleTags ?? []).map((t) => String(t).toLowerCase());
+        if (!tags.some((t) => t.includes(needle) || needle.includes(t)))
+            return false;
+    }
+    if (opts.aspect) {
+        const want = opts.aspect.toLowerCase();
+        const ratios = (tpl.supportedAspectRatios ?? []).map((r) => String(r).toLowerCase());
+        if (!ratios.includes(want))
+            return false;
+    }
+    if (opts.language) {
+        // Unknown language (absent/empty) is never excluded by a language filter.
+        const langs = (tpl.contentLanguage ?? []).map((l) => String(l).toLowerCase());
+        if (langs.length > 0 && !langs.includes(opts.language.toLowerCase()))
+            return false;
+    }
+    return true;
+}
+export async function templateBind(input, _ctx) {
+    // The skill currently exposes exactly one CLI verb. Treat missing flag as
+    // list-templates too, matching match_template.py's "no args == list" behavior.
+    const wantsList = input.list_templates === true || input.list_templates === 'true' || Object.keys(input).length === 0 ||
+        typeof input.filter_tag === 'string' || typeof input.filter_aspect === 'string' ||
+        typeof input.filter_language === 'string' ||
+        input.include_beta === true || input.include_beta === 'true';
+    if (!wantsList) {
+        throw new SkillError('template-bind CLI only supports --list-templates [--filter-tag X] [--filter-aspect X] [--filter-language zh|en] [--include-beta]; binding logic is invoked in-process by render-video and is not exposed as a CLI verb.');
+    }
+    // P2.2: status gating mirrors registry_loader.py — only stable by default,
+    // beta unlocked by env var or explicit --include-beta flag.
+    const allowed = visibleStatuses();
+    if (input.include_beta === true || input.include_beta === 'true')
+        allowed.add('beta');
+    const tagFilter = typeof input.filter_tag === 'string' ? input.filter_tag : undefined;
+    const aspectFilter = typeof input.filter_aspect === 'string' ? input.filter_aspect : undefined;
+    const languageFilter = typeof input.filter_language === 'string' ? input.filter_language : undefined;
+    const registry = await loadRegistry();
+    const all = registry.templates ?? [];
+    const visible = all.filter((t) => allowed.has(statusOf(t)) && matchesFilter(t, { tag: tagFilter, aspect: aspectFilter, language: languageFilter }));
+    if (visible.length === 0) {
+        const hiddenCount = all.length - visible.length;
+        process.stdout.write(`⚠️  No templates match the current filters (${hiddenCount} hidden by status/filter; check --include-beta or relax --filter-*).\n`);
+        return;
+    }
+    process.stdout.write(`\n${'Template ID'.padEnd(22)} ${'Name'.padEnd(18)} ${'Aspect'.padEnd(12)} ${'Lang'.padEnd(8)} ${'Status'.padEnd(8)} Tags / LLM hint\n`);
+    process.stdout.write(`${'-'.repeat(22)} ${'-'.repeat(18)} ${'-'.repeat(12)} ${'-'.repeat(8)} ${'-'.repeat(8)} ${'-'.repeat(60)}\n`);
+    for (const tpl of visible) {
+        const tid = (tpl.templateId ?? '').padEnd(22);
+        const name = (tpl.name ?? '').padEnd(18);
+        const ratios = (tpl.supportedAspectRatios ?? []).join(',').padEnd(12);
+        const lang = ((tpl.contentLanguage ?? []).join(',') || '-').padEnd(8);
+        const st = statusOf(tpl).padEnd(8);
+        const tags = (tpl.styleTags ?? []).slice(0, 5).join(', ');
+        process.stdout.write(`${tid} ${name} ${ratios} ${lang} ${st} ${tags}\n`);
+        if (tpl.llmHint) {
+            // Indent the hint so it visually belongs to the row above. Truncated to
+            // keep `--list-templates` scannable at 100+ templates.
+            const hint = tpl.llmHint.length > 200 ? tpl.llmHint.slice(0, 197) + '...' : tpl.llmHint;
+            process.stdout.write(`${' '.repeat(22)}   ↳ ${hint}\n`);
+        }
+    }
+    const hidden = all.length - visible.length;
+    const hiddenNote = hidden > 0 ? ` (${hidden} hidden by status/filter)` : '';
+    process.stdout.write(`\n${visible.length} template(s) shown${hiddenNote}\n`);
+}

package/dist/http.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared HTTP helpers for ab-api endpoints.
+ *
+ * Centralizes the auth contract (X-Priv-Token + x-invoke-skill / x-invoke-agent /
+ * x-conversation-id), business-code error handling (result.code != 0), and the
+ * env var resolution order that every Python skill used to duplicate.
+ *
+ * Token resolution order (high → low):
+ *   1. opts.privateToken                — caller override
+ *   2. process.env.PRIV_TOKEN           — process env
+ *   3. throws SkillError                — non-interactive failure
+ *
+ * Base URL resolution:
+ *   1. opts.apiBaseUrl                  — caller override
+ *   2. process.env.MM_API_BASE_URL      — process env
+ *   3. http://localhost:2999/api        — local dev fallback
+ */
+export declare class SkillError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+export interface HttpContext {
+    apiBaseUrl: string;
+    privateToken: string;
+    skillName: string;
+    agentName?: string;
+    conversationId?: string;
+}
+export declare function resolveHttpContext(skillName: string, opts?: {
+    apiBaseUrl?: string;
+    privateToken?: string;
+}): HttpContext;
+export interface MmResponse<T = unknown> {
+    code: number;
+    msg?: string;
+    data?: T;
+}
+/**
+ * POST JSON to ab-api and return the parsed business payload.
+ * Throws SkillError on HTTP errors or business code != 0.
+ */
+export declare function mmPost<T = unknown>(ctx: HttpContext, pathOrUrl: string, body: unknown, opts?: {
+    timeoutMs?: number;
+}): Promise<T>;
+/**
+ * Generic polling helper. Repeatedly invokes `probe()` every `intervalMs`
+ * until it returns a non-null value or `timeoutMs` elapses.
+ */
+export declare function pollUntil<T>(probe: () => Promise<T | null>, opts?: {
+    intervalMs?: number;
+    timeoutMs?: number;
+}): Promise<T>;

package/dist/http.js

@@ -0,0 +1,110 @@
+/**
+ * Shared HTTP helpers for ab-api endpoints.
+ *
+ * Centralizes the auth contract (X-Priv-Token + x-invoke-skill / x-invoke-agent /
+ * x-conversation-id), business-code error handling (result.code != 0), and the
+ * env var resolution order that every Python skill used to duplicate.
+ *
+ * Token resolution order (high → low):
+ *   1. opts.privateToken                — caller override
+ *   2. process.env.PRIV_TOKEN           — process env
+ *   3. throws SkillError                — non-interactive failure
+ *
+ * Base URL resolution:
+ *   1. opts.apiBaseUrl                  — caller override
+ *   2. process.env.MM_API_BASE_URL      — process env
+ *   3. http://localhost:2999/api        — local dev fallback
+ */
+const DEFAULT_API_BASE_URL = 'http://localhost:2999/api';
+export class SkillError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = 'SkillError';
+    }
+}
+export function resolveHttpContext(skillName, opts = {}) {
+    const apiBaseUrl = (opts.apiBaseUrl ?? process.env.MM_API_BASE_URL ?? DEFAULT_API_BASE_URL).replace(/\/+$/, '');
+    const privateToken = opts.privateToken ?? process.env.PRIV_TOKEN ?? '';
+    if (!privateToken) {
+        throw new SkillError('❌ PRIV_TOKEN is not configured (set the env var or pass --priv-token)');
+    }
+    return {
+        apiBaseUrl,
+        privateToken,
+        skillName,
+        agentName: process.env.AGENT_NAME || undefined,
+        conversationId: process.env.CONVERSATION_ID || undefined,
+    };
+}
+function buildHeaders(ctx, extra) {
+    const headers = {
+        'Content-Type': 'application/json',
+        'X-Priv-Token': ctx.privateToken,
+        'x-invoke-skill': ctx.skillName,
+    };
+    if (ctx.agentName)
+        headers['x-invoke-agent'] = ctx.agentName;
+    if (ctx.conversationId)
+        headers['x-conversation-id'] = ctx.conversationId;
+    return { ...headers, ...extra };
+}
+/**
+ * POST JSON to ab-api and return the parsed business payload.
+ * Throws SkillError on HTTP errors or business code != 0.
+ */
+export async function mmPost(ctx, pathOrUrl, body, opts = {}) {
+    const url = pathOrUrl.startsWith('http') ? pathOrUrl : `${ctx.apiBaseUrl}${pathOrUrl}`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), opts.timeoutMs ?? 120_000);
+    let resp;
+    try {
+        resp = await fetch(url, {
+            method: 'POST',
+            headers: buildHeaders(ctx),
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+            throw new SkillError(`❌ request timed out: ${url}`);
+        }
+        throw new SkillError(`❌ network error: ${err.message}`);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+    const text = await resp.text();
+    if (!resp.ok) {
+        throw new SkillError(`❌ API request failed (HTTP ${resp.status}): ${text}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new SkillError(`❌ failed to parse response, body is not JSON: ${text.slice(0, 200)}`);
+    }
+    if (parsed.code !== 0) {
+        throw new SkillError(`❌ API returned a business error: ${parsed.msg ?? 'unknown error'} (code=${parsed.code})`);
+    }
+    return parsed.data ?? undefined;
+}
+/**
+ * Generic polling helper. Repeatedly invokes `probe()` every `intervalMs`
+ * until it returns a non-null value or `timeoutMs` elapses.
+ */
+export async function pollUntil(probe, opts = {}) {
+    const intervalMs = opts.intervalMs ?? 5_000;
+    const timeoutMs = opts.timeoutMs ?? 120_000;
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        await new Promise((r) => setTimeout(r, intervalMs));
+        const result = await probe();
+        if (result !== null)
+            return result;
+    }
+    throw new SkillError(`❌ polling timed out (${Math.round(timeoutMs / 1000)}s)`);
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * remixmate — public library exports.
+ *
+ * The CLI entrypoint lives in `cli.ts` (`bin: remixmate`). This file is the
+ * library surface for type-sharing consumers; the published npm package
+ * exposes it via `main: dist/index.js` / `types: dist/index.d.ts`.
+ */
+export { loadSkills, findSkill, SKILLS_DIR } from './registry.js';
+export type { SkillDef, SkillEntry } from './registry.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * remixmate — public library exports.
+ *
+ * The CLI entrypoint lives in `cli.ts` (`bin: remixmate`). This file is the
+ * library surface for type-sharing consumers; the published npm package
+ * exposes it via `main: dist/index.js` / `types: dist/index.d.ts`.
+ */
+export { loadSkills, findSkill, SKILLS_DIR } from './registry.js';

package/dist/manifest.json

@@ -0,0 +1,260 @@
+{
+  "schemaVersion": 1,
+  "version": "0.1.0",
+  "generatedAt": "2026-06-06T15:02:44.292Z",
+  "skills": [
+    {
+      "id": "export-jianying",
+      "tier": "orchestration",
+      "title": "Jianying (CapCut) Draft Export",
+      "summary": "Jianying (CapCut) draft export: package asset URLs into a draft ZIP that Jianying can import. Supports automatic conversion from a RenderPlan.",
+      "triggers": [
+        "Export to Jianying, Jianying draft, package for Jianying, import into Jianying",
+        "Export materials to the Jianying format, generate a Jianying project",
+        "Bundle video / image / audio into a Jianying draft",
+        "Export a Jianying draft from a RenderPlan"
+      ],
+      "entry": {
+        "type": "python",
+        "scriptPath": "scripts/gen_jianying_draft.py"
+      },
+      "runtime": "python",
+      "envVars": [
+        "PRIV_TOKEN",
+        "MM_API_BASE_URL",
+        "AGENT_NAME"
+      ]
+    },
+    {
+      "id": "gen-digital-human",
+      "tier": "atomic",
+      "title": "Digital-Human Talking-Head",
+      "summary": "Digital-human video: list available avatars; produce a talking-head video from text via TTS, or drive an avatar from an existing audio URL.",
+      "triggers": [
+        "Digital human, talking-head video, AI presenter, virtual host",
+        "Make a talking-head video out of this script / this audio file",
+        "List or browse digital-human avatars",
+        "Use Jimeng or HiFly to drive an avatar"
+      ],
+      "entry": {
+        "type": "python",
+        "scriptPath": "scripts/gen_digital_human_video.py"
+      },
+      "runtime": "python",
+      "envVars": [
+        "PRIV_TOKEN",
+        "MM_API_BASE_URL",
+        "AGENT_NAME"
+      ]
+    },
+    {
+      "id": "gen-image",
+      "tier": "atomic",
+      "title": "AI Image Generation",
+      "summary": "AI image generation: produce an image from a text prompt. Supports Seedream and Gemini models, plus image-to-image with reference images.",
+      "triggers": [
+        "AI image generation, text-to-image, \"draw me ...\", \"generate an image of ...\"",
+        "Image-to-image, reference image, style transfer, image variation",
+        "Generate an image with Doubao / Seedream / Gemini",
+        "Provide a prompt and ask for an image"
+      ],
+      "entry": {
+        "type": "http",
+        "handler": "gen-image"
+      },
+      "runtime": "node",
+      "envVars": [
+        "PRIV_TOKEN",
+        "MM_API_BASE_URL",
+        "AGENT_NAME",
+        "MM_IMAGE_MODEL"
+      ]
+    },
+    {
+      "id": "gen-script",
+      "tier": "orchestration",
+      "title": "Video Script Generation",
+      "summary": "Video script generation: turn a topic into a structured Video DSL (JSON) that describes the full video — scene structure, asset requirements, and narrative flow.",
+      "triggers": [
+        "Write a video script, generate a video script, plan a video, write storyboards",
+        "Create a short video, plan video content, generate a Video DSL",
+        "Turn a topic into a video structure / video content plan"
+      ],
+      "entry": {
+        "type": "python",
+        "scriptPath": "scripts/gen_script.py"
+      },
+      "runtime": "python",
+      "envVars": [
+        "DEFAULT_IMAGE_MODEL",
+        "DEFAULT_VIDEO_MODEL",
+        "STUB_IMAGE_URL",
+        "STUB_VIDEO_URL"
+      ]
+    },
+    {
+      "id": "gen-video",
+      "tier": "atomic",
+      "title": "AI Video Generation",
+      "summary": "AI video generation: produce a short video clip from a text prompt. Supports Seedance and Veo models, plus first/last frame and reference images.",
+      "triggers": [
+        "Text-to-video, AI-generated clip, \"make a short video of ...\"",
+        "Generate video with Doubao / Seedance / Veo / Google",
+        "Image-to-video, first-frame / last-frame, reference-image-to-video"
+      ],
+      "entry": {
+        "type": "python",
+        "scriptPath": "scripts/gen_video.py"
+      },
+      "runtime": "python",
+      "envVars": [
+        "PRIV_TOKEN",
+        "MM_API_BASE_URL",
+        "AGENT_NAME",
+        "MM_VIDEO_MODEL"
+      ]
+    },
+    {
+      "id": "gen-voice",
+      "tier": "atomic",
+      "title": "Text-to-Speech (Minimax)",
+      "summary": "Text-to-speech (TTS): synthesize narration audio from text via the Minimax TTS model. Returns the persisted audio URL — no download needed.",
+      "triggers": [
+        "AI voice-over, TTS, text-to-speech, generate narration audio",
+        "Use Minimax for speech synthesis",
+        "Read a piece of text aloud / produce an audio file from text"
+      ],
+      "entry": {
+        "type": "http",
+        "handler": "gen-voice"
+      },
+      "runtime": "node",
+      "envVars": [
+        "PRIV_TOKEN",
+        "MM_API_BASE_URL",
+        "AGENT_NAME"
+      ]
+    },
+    {
+      "id": "prepare-video-assets",
+      "tier": "orchestration",
+      "title": "Video Asset Preparation",
+      "summary": "Resolves and generates every asset (image / audio / video) referenced by a Video DSL, persists a RenderPlan to the database, and returns a job_id for the subsequent render_video call. This is Phase 1 of the two-phase video pipeline; Phase 3 (Remotion render) lives in render_video.",
+      "triggers": [
+        "Generate / prepare video assets",
+        "Resolve missing assets in a DSL",
+        "User confirmed the script and the agent needs to prepare assets for review",
+        "User asks to regenerate a specific scene's image or narration"
+      ],
+      "entry": {
+        "type": "python",
+        "scriptPath": "scripts/prepare_video_assets.py"
+      },
+      "runtime": "python",
+      "envVars": [
+        "PRIV_TOKEN",
+        "MM_API_BASE_URL",
+        "MM_BACKEND_API_URL",
+        "AGENT_NAME",
+        "REMOTION_RENDER_API_URL",
+        "REMOTION_RENDER_MODE",
+        "REMOTION_OUTPUT_DIR",
+        "ASSET_CACHE_DIR"
+      ]
+    },
+    {
+      "id": "render-video",
+      "tier": "orchestration",
+      "title": "Remotion Video Renderer",
+      "summary": "Loads a persisted RenderPlan by job_id and drives the Remotion engine to produce the final video. Assets must already be generated via prepare_video_assets — this skill never resolves or regenerates assets.",
+      "triggers": [
+        "Render the video, composite the video, export the video",
+        "Turn the prepared assets into the final clip",
+        "Render with Remotion",
+        "Agent has a job_id from prepare_video_assets and needs the final video"
+      ],
+      "entry": {
+        "type": "python",
+        "scriptPath": "scripts/render_video.py"
+      },
+      "runtime": "python",
+      "envVars": [
+        "PRIV_TOKEN",
+        "MM_API_BASE_URL",
+        "MM_BACKEND_API_URL",
+        "AGENT_NAME",
+        "REMOTION_RENDER_API_URL",
+        "REMOTION_RENDER_MODE",
+        "REMOTION_OUTPUT_DIR",
+        "ASSET_CACHE_DIR"
+      ]
+    },
+    {
+      "id": "template-bind",
+      "tier": "orchestration",
+      "title": "Template Registry (List-only)",
+      "summary": "List all available video templates (templateId / name / aspect ratio / style tags). Template-to-DSL binding is no longer exposed as a separate step — once prepare_video_assets receives a template_id it runs the full DSL→RenderPlan pipeline internally.",
+      "triggers": [
+        "View available templates / list every template",
+        "Bind a template to a DSL (a template-id must be supplied)",
+        "Agent has a Video DSL and needs a TemplateBinding"
+      ],
+      "entry": {
+        "type": "builtin",
+        "handler": "template-bind"
+      },
+      "runtime": "node",
+      "envVars": [
+        "PRIV_TOKEN",
+        "VIDEO_TEMPLATE_REGISTRY",
+        "VIDEO_TEMPLATE_REGISTRY_URL",
+        "VIDEO_TEMPLATE_REGISTRY_HTTP_METHOD"
+      ]
+    },
+    {
+      "id": "video-parser",
+      "tier": "tool",
+      "title": "Video Deconstruction",
+      "summary": "Video deconstruction: split a video into reusable assets (audio extraction, ASR transcript, keyframe extraction, scene segmentation).",
+      "triggers": [
+        "Deconstruct / split / analyze / parse a video",
+        "Extract keyframes, extract the script from a video, transcribe a video",
+        "Pull content assets or raw material out of a video"
+      ],
+      "entry": {
+        "type": "python",
+        "scriptPath": "scripts/parse_via_render.py"
+      },
+      "runtime": "python",
+      "envVars": [
+        "PRIV_TOKEN",
+        "MM_API_BASE_URL",
+        "AGENT_NAME",
+        "RENDER_API_URL"
+      ]
+    },
+    {
+      "id": "web-capture",
+      "tier": "tool",
+      "title": "Web Page Capture",
+      "summary": "Drive a headless browser (Playwright) to capture a web page: viewport/full-page screenshots, or a smooth top-to-bottom scrolling video. Produces PNG / MP4 assets that feed the screen-walkthrough template.",
+      "triggers": [
+        "Screenshot a web page / website / a specific URL, full-page screenshot",
+        "Record a page scrolling top-to-bottom into a video, \"scroll video\" of a site",
+        "Produce screen-recording / walkthrough footage of a GitHub repo, landing page, or product page"
+      ],
+      "entry": {
+        "type": "python",
+        "scriptPath": "scripts/web_capture.py"
+      },
+      "runtime": "python",
+      "envVars": [
+        "WEB_CAPTURE_BROWSER",
+        "WEB_CAPTURE_OUTPUT_BASE",
+        "WEB_CAPTURE_NO_SANDBOX",
+        "WEB_CAPTURE_ALLOW_PRIVATE_HOSTS",
+        "PLAYWRIGHT_BROWSERS_PATH"
+      ]
+    }
+  ]
+}

package/dist/progress.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Progress reporting — emits __progress__ JSON lines that ab-agent's
+ * executor parses (see apps/ab-agent/src/skills/executor.ts).
+ *
+ * Always writes to stdout because the consumer reads stdout line-by-line.
+ * Each event is a single JSON object on its own line, with the marker
+ * field `__progress__: true` so non-progress stdout content is ignored.
+ *
+ * The consumer flattens the entire parsed JSON into `extra`, so any
+ * additional context (model id, generationId, ...) can be passed as
+ * top-level keys and will reach the SSE client unchanged.
+ */
+export interface ProgressEvent {
+    /** Pipeline phase, e.g. `gen-image:request`. */
+    phase?: string;
+    /** 0..1 progress fraction. */
+    progress?: number;
+    etaSeconds?: number | null;
+    elapsedSeconds?: number | null;
+    /** Free-form context — flattened into the parsed JSON line. */
+    [key: string]: unknown;
+}
+export declare function emitProgress(ev: ProgressEvent): void;

package/dist/progress.js

@@ -0,0 +1,15 @@
+/**
+ * Progress reporting — emits __progress__ JSON lines that ab-agent's
+ * executor parses (see apps/ab-agent/src/skills/executor.ts).
+ *
+ * Always writes to stdout because the consumer reads stdout line-by-line.
+ * Each event is a single JSON object on its own line, with the marker
+ * field `__progress__: true` so non-progress stdout content is ignored.
+ *
+ * The consumer flattens the entire parsed JSON into `extra`, so any
+ * additional context (model id, generationId, ...) can be passed as
+ * top-level keys and will reach the SSE client unchanged.
+ */
+export function emitProgress(ev) {
+    process.stdout.write(JSON.stringify({ __progress__: true, ...ev }) + '\n');
+}