@prestyj/editor 0.7.1

package/dist/tools/add-sfx-to-timeline.js

@@ -0,0 +1,169 @@
+import { z } from "zod";
+import { bundledSfxDescriptionList, listBundledSfxNames, resolveSfx } from "../core/bundled-sfx.js";
+import { compact, err } from "../core/format.js";
+import { checkFfmpeg } from "../core/media/ffmpeg.js";
+/**
+ * add_sfx_to_timeline — drop SFX clips DIRECTLY onto the active timeline's
+ * audio track at each cut point. Sibling of `add_sfx_at_cuts` but operates
+ * on the live host (Resolve / Premiere) instead of producing a new mp4.
+ *
+ * Why this exists: `add_sfx_at_cuts` is file-only — it bakes SFX into a
+ * rendered mp4. That's right for "ship the final file" workflows but wrong
+ * when the user wants the SFX in the timeline so they can keep editing,
+ * tune levels in Fairlight, or hear it on playback in Resolve.
+ *
+ * Mechanics:
+ *   1. Resolve the SFX (bundled name → synthesise via ffmpeg / cache;
+ *      file path → pass through).
+ *   2. Get the timeline frame rate (needed to convert seconds → record frames).
+ *   3. For each cut point: place the SFX wav at that record frame on the
+ *      target audio track via `host.insertClipOnTrack(mediaKind="audio")`.
+ *
+ * Volume / ducking: the inserted clips land at unity gain. Use Fairlight
+ * (Resolve) or Audio Mixer (Premiere) to adjust per-clip levels — Fairlight
+ * isn't scriptable so we don't try.
+ */
+const AddSfxToTimelineParams = z.object({
+    sfx: z
+        .string()
+        .describe(`SFX. Pass a bundled name (synthesised on demand at ~/.ezcoder/sfx-cache/) OR a file path. ` +
+        `Bundled names: ${listBundledSfxNames().join(", ")}.`),
+    cutPoints: z
+        .array(z.number().min(0))
+        .min(1)
+        .describe("TIMELINE-space timestamps (seconds) where the SFX should fire. ⚠️ These must be " +
+        "timeline-relative — NOT source-video timestamps from the transcript. After " +
+        "`cut_filler_words` runs, use the `timelineCutPoints` field from its result; passing " +
+        "source-space transcript timestamps causes the SFX to drift further out of sync after " +
+        "every cut (fine for the first ~30 s, off by 20+ s by the end). Closer-than-" +
+        "minSpacingSec hits are deduped."),
+    track: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("Target audio track (1-indexed). Default 3 — keeps A1 (dialogue) and A2 (music) free. " +
+        "If the track doesn't exist, run add_track(kind='audio') first."),
+    frameRate: z
+        .number()
+        .positive()
+        .optional()
+        .describe("Override timeline frame rate. Auto-detected via get_timeline; pass when host_info " +
+        "shows an unusual project fps and the agent has it cached."),
+    minSpacingSec: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("Min spacing between hits. Closer cuts are dropped (avoids 8 stacked whooshes on " +
+        "machine-gun edits). Default 0.25 s."),
+});
+export function createAddSfxToTimelineTool(host, cwd) {
+    return {
+        name: "add_sfx_to_timeline",
+        description: `Insert a SFX clip directly onto the active timeline's audio track at each cut point. ` +
+            `LIVE host operation \u2014 unlike add_sfx_at_cuts which bakes SFX into a rendered mp4, ` +
+            `this drops actual audio clips into Resolve/Premiere so the user hears them on ` +
+            `playback and can tune levels in Fairlight. Bundled SFX (synthesised on demand): ` +
+            `${bundledSfxDescriptionList()}. Defaults to track A3 (keeps A1 dialogue / A2 music free); ` +
+            `pass track= to override. Pair with cut_filler_words / detect_silence cut-point lists.`,
+        parameters: AddSfxToTimelineParams,
+        async execute(args, ctx) {
+            // ffmpeg only required if the user passed a bundled SFX name (we synthesise).
+            // For a literal file path, no ffmpeg dep here \u2014 Resolve/Premiere handles import.
+            try {
+                // Resolve SFX to an absolute path (synthesise bundled name if cache miss).
+                let sfxAbs;
+                let sfxInfo;
+                try {
+                    const r = await resolveSfx(args.sfx, cwd, ctx.signal);
+                    sfxAbs = r.path;
+                    sfxInfo = { bundled: r.bundled, name: r.name };
+                }
+                catch (e) {
+                    // Bundled-name failures often surface via ffmpeg synthesis errors;
+                    // surface ffmpeg presence in the fix hint when relevant.
+                    const msg = e.message;
+                    const hint = msg.includes("ffmpeg") || msg.includes("Bundled:")
+                        ? checkFfmpeg()
+                            ? "use a bundled SFX name or supply a real file path"
+                            : "ffmpeg not on PATH \u2014 install ffmpeg or use a literal file path"
+                        : "use a bundled SFX name or supply a real file path";
+                    return err(msg, hint);
+                }
+                // Determine timeline frame rate.
+                let fps = args.frameRate;
+                if (fps === undefined) {
+                    try {
+                        const tl = await host.getTimeline();
+                        fps = tl.frameRate;
+                    }
+                    catch (e) {
+                        return err(`cannot read timeline framerate: ${e.message}`, "open Resolve/Premiere with an active timeline OR pass frameRate=...");
+                    }
+                }
+                if (!fps || fps <= 0) {
+                    return err("could not determine timeline frame rate", "pass frameRate=24/25/30/60 explicitly");
+                }
+                // Sort + dedup cut points by minSpacingSec.
+                const minSpacing = args.minSpacingSec ?? 0.25;
+                const sortedCuts = [...args.cutPoints].sort((a, b) => a - b);
+                const filtered = [];
+                for (const c of sortedCuts) {
+                    if (c < 0)
+                        continue;
+                    if (filtered.length === 0 || c - filtered[filtered.length - 1] >= minSpacing) {
+                        filtered.push(c);
+                    }
+                }
+                if (filtered.length === 0) {
+                    return err("no usable cut points after filtering");
+                }
+                // Insert each SFX. Track failures per-cut so a single bad insertion
+                // doesn't kill the whole batch.
+                const track = args.track ?? 3;
+                const inserted = [];
+                const failed = [];
+                for (const atSec of filtered) {
+                    if (ctx.signal?.aborted) {
+                        return err("aborted");
+                    }
+                    const recordFrame = Math.round(atSec * fps);
+                    try {
+                        const r = await host.insertClipOnTrack({
+                            mediaPath: sfxAbs,
+                            track,
+                            recordFrame,
+                            mediaKind: "audio",
+                        });
+                        inserted.push({ atSec: +atSec.toFixed(3), recordFrame, clipId: r.id });
+                    }
+                    catch (e) {
+                        failed.push({ atSec: +atSec.toFixed(3), error: e.message });
+                    }
+                }
+                if (inserted.length === 0) {
+                    // Surface the first error so the user sees what went wrong (likely
+                    // missing audio track \u2014 the agent should add_track('audio') first).
+                    const firstErr = failed[0]?.error ?? "no clips inserted";
+                    return err(`no SFX clips inserted on track A${track}: ${firstErr}`, `track A${track} may not exist \u2014 run add_track(kind='audio') first, or pick a lower track`);
+                }
+                return compact({
+                    ok: true,
+                    inserted: inserted.length,
+                    failed: failed.length || undefined,
+                    track,
+                    fps,
+                    sfx: sfxInfo.bundled ? `bundled:${sfxInfo.name}` : sfxAbs,
+                    // Sample of inserted clips so the agent can quote what landed where.
+                    sample: inserted.slice(0, 5),
+                    // Per-failure detail for the agent to retry / diagnose.
+                    failures: failed.length ? failed.slice(0, 5) : undefined,
+                });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=add-sfx-to-timeline.js.map

package/dist/tools/add-sfx-to-timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-sfx-to-timeline.js","sourceRoot":"","sources":["../../src/tools/add-sfx-to-timeline.ts"],"names":[],"mappings":"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"}

package/dist/tools/add-sfx-to-timeline.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=add-sfx-to-timeline.test.d.ts.map

package/dist/tools/add-sfx-to-timeline.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-sfx-to-timeline.test.d.ts","sourceRoot":"","sources":["../../src/tools/add-sfx-to-timeline.test.ts"],"names":[],"mappings":""}

package/dist/tools/add-sfx-to-timeline.test.js

@@ -0,0 +1,181 @@
+import { describe, expect, it, vi } from "vitest";
+import { createAddSfxToTimelineTool } from "./add-sfx-to-timeline.js";
+// Mock bundled-sfx so the tool tests don't try to spawn ffmpeg.
+vi.mock("../core/bundled-sfx.js", async () => {
+    /* eslint-disable @typescript-eslint/consistent-type-imports */
+    const actual = await vi.importActual("../core/bundled-sfx.js");
+    /* eslint-enable @typescript-eslint/consistent-type-imports */
+    return {
+        ...actual,
+        resolveSfx: vi.fn(async (name) => {
+            if (name === "whoosh") {
+                return { path: "/cache/whoosh.wav", bundled: true, name: "whoosh" };
+            }
+            if (name === "/abs/custom.wav") {
+                return { path: "/abs/custom.wav", bundled: false };
+            }
+            throw new Error(`unknown SFX name: '${name}'. Bundled: pop, whoosh`);
+        }),
+    };
+});
+const ctx = {
+    signal: new AbortController().signal,
+    toolCallId: "t1",
+};
+// Loose mock helpers — we don't import the internal types since some
+// (ClipInfo / TimelineState) aren't part of the public type surface.
+function mockHost(opts) {
+    const defaultInsert = async ({ recordFrame, track, mediaKind, }) => ({
+        id: `clip-${recordFrame}`,
+        track: track ?? 3,
+        trackKind: (mediaKind ?? "video"),
+        startFrame: recordFrame,
+        endFrame: recordFrame + 9,
+        name: "whoosh.wav",
+    });
+    const insertSpy = opts.insert ?? defaultInsert;
+    return {
+        name: "resolve",
+        capabilities: () => Promise.resolve({
+            isAvailable: true,
+            canMoveClips: false,
+            canScriptColor: true,
+            canScriptAudio: false,
+            canTriggerAI: false,
+            preferredImportFormat: "edl",
+        }),
+        getTimeline: () => {
+            if (opts.getTimelineErr)
+                return Promise.reject(opts.getTimelineErr);
+            return Promise.resolve({
+                frameRate: opts.fps ?? 30,
+                fps: opts.fps ?? 30,
+            });
+        },
+        insertClipOnTrack: insertSpy,
+    };
+}
+describe("add_sfx_to_timeline", () => {
+    it("converts seconds to frames using timeline fps and inserts on the requested audio track", async () => {
+        const insert = async ({ recordFrame, track, mediaKind, mediaPath, }) => ({
+            id: `c-${recordFrame}`,
+            track,
+            trackKind: (mediaKind ?? "video"),
+            startFrame: recordFrame,
+            endFrame: recordFrame + 9,
+            name: mediaPath.split("/").pop() ?? "x",
+        });
+        const insertSpy = vi.fn(insert);
+        const tool = createAddSfxToTimelineTool(mockHost({ fps: 30, insert: insertSpy }), "/cwd");
+        const r = await tool.execute({ sfx: "whoosh", cutPoints: [1, 2, 5.5], track: 3 }, ctx);
+        const out = JSON.parse(r);
+        expect(out.ok).toBe(true);
+        expect(out.inserted).toBe(3);
+        expect(out.track).toBe(3);
+        expect(out.fps).toBe(30);
+        expect(out.sfx).toBe("bundled:whoosh");
+        // Verify each insertion went via the audio path with correct frame conversion.
+        expect(insertSpy).toHaveBeenCalledTimes(3);
+        expect(insertSpy).toHaveBeenNthCalledWith(1, {
+            mediaPath: "/cache/whoosh.wav",
+            track: 3,
+            recordFrame: 30,
+            mediaKind: "audio",
+        });
+        expect(insertSpy).toHaveBeenNthCalledWith(2, {
+            mediaPath: "/cache/whoosh.wav",
+            track: 3,
+            recordFrame: 60,
+            mediaKind: "audio",
+        });
+        expect(insertSpy).toHaveBeenNthCalledWith(3, {
+            mediaPath: "/cache/whoosh.wav",
+            track: 3,
+            recordFrame: 165,
+            mediaKind: "audio",
+        });
+    });
+    it("dedupes cuts closer than minSpacingSec", async () => {
+        const insert = vi.fn(async () => ({
+            id: "c",
+            track: 3,
+            trackKind: "audio",
+            startFrame: 0,
+            endFrame: 9,
+            name: "w",
+        }));
+        const tool = createAddSfxToTimelineTool(mockHost({ fps: 30, insert }), "/cwd");
+        await tool.execute({ sfx: "whoosh", cutPoints: [1, 1.05, 1.1, 5], minSpacingSec: 0.25 }, ctx);
+        expect(insert).toHaveBeenCalledTimes(2); // 1.0 and 5.0 only
+    });
+    it("uses default track A3 when not specified", async () => {
+        const insert = vi.fn(async () => ({
+            id: "c",
+            track: 3,
+            trackKind: "audio",
+            startFrame: 0,
+            endFrame: 9,
+            name: "w",
+        }));
+        const tool = createAddSfxToTimelineTool(mockHost({ fps: 30, insert }), "/cwd");
+        await tool.execute({ sfx: "whoosh", cutPoints: [1] }, ctx);
+        expect(insert).toHaveBeenCalledWith(expect.objectContaining({ track: 3, mediaKind: "audio" }));
+    });
+    it("fails clean with a host hint when the audio track doesn't exist", async () => {
+        const insert = async () => {
+            throw new Error("track 7 does not exist on active sequence.");
+        };
+        const tool = createAddSfxToTimelineTool(mockHost({ fps: 30, insert }), "/cwd");
+        const r = await tool.execute({ sfx: "whoosh", cutPoints: [1, 2], track: 7 }, ctx);
+        expect(r).toMatch(/^error:/);
+        expect(r).toMatch(/add_track\(kind='audio'\)/);
+    });
+    it("partial-success: some inserts fail, returns ok with failures detail", async () => {
+        let n = 0;
+        const insert = async ({ recordFrame }) => {
+            n++;
+            if (n === 2)
+                throw new Error("transient bridge error");
+            return {
+                id: `c-${recordFrame}`,
+                track: 3,
+                trackKind: "audio",
+                startFrame: recordFrame,
+                endFrame: recordFrame + 9,
+                name: "w",
+            };
+        };
+        const tool = createAddSfxToTimelineTool(mockHost({ fps: 30, insert }), "/cwd");
+        const r = await tool.execute({ sfx: "whoosh", cutPoints: [1, 2, 3] }, ctx);
+        const out = JSON.parse(r);
+        expect(out.inserted).toBe(2);
+        expect(out.failed).toBe(1);
+    });
+    it("respects explicit frameRate override", async () => {
+        const insert = async ({ recordFrame }) => ({
+            id: `c-${recordFrame}`,
+            track: 3,
+            trackKind: "audio",
+            startFrame: recordFrame,
+            endFrame: recordFrame + 9,
+            name: "w",
+        });
+        const insertSpy = vi.fn(insert);
+        const tool = createAddSfxToTimelineTool(mockHost({ fps: 30, insert: insertSpy }), "/cwd");
+        await tool.execute({ sfx: "whoosh", cutPoints: [1], frameRate: 60 }, ctx);
+        expect(insertSpy).toHaveBeenCalledWith(expect.objectContaining({ recordFrame: 60 }));
+    });
+    it("propagates unknown SFX name errors with the bundled list in the hint", async () => {
+        const tool = createAddSfxToTimelineTool(mockHost({ fps: 30 }), "/cwd");
+        const r = await tool.execute({ sfx: "notarealsfx", cutPoints: [1] }, ctx);
+        expect(r).toMatch(/error: unknown SFX name/);
+        expect(r).toMatch(/bundled SFX name/);
+    });
+    it("rejects when the host can't report a frame rate", async () => {
+        const tool = createAddSfxToTimelineTool(mockHost({ getTimelineErr: new Error("host=none") }), "/cwd");
+        const r = await tool.execute({ sfx: "whoosh", cutPoints: [1] }, ctx);
+        expect(r).toMatch(/cannot read timeline framerate/);
+        expect(r).toMatch(/frameRate=/);
+    });
+});
+//# sourceMappingURL=add-sfx-to-timeline.test.js.map

package/dist/tools/add-sfx-to-timeline.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-sfx-to-timeline.test.js","sourceRoot":"","sources":["../../src/tools/add-sfx-to-timeline.test.ts"],"names":[],"mappings":"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"}

package/dist/tools/add-track.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+import type { VideoHost } from "../core/hosts/types.js";
+declare const AddTrackParams: z.ZodObject<{
+    kind: z.ZodEnum<{
+        video: "video";
+        audio: "audio";
+        subtitle: "subtitle";
+    }>;
+}, z.core.$strip>;
+export declare function createAddTrackTool(host: VideoHost): AgentTool<typeof AddTrackParams>;
+export {};
+//# sourceMappingURL=add-track.d.ts.map

package/dist/tools/add-track.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-track.d.ts","sourceRoot":"","sources":["../../src/tools/add-track.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD,QAAA,MAAM,cAAc;;;;;;iBAIlB,CAAC;AAEH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC,OAAO,cAAc,CAAC,CAiBpF"}

package/dist/tools/add-track.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { compact, err } from "../core/format.js";
+const AddTrackParams = z.object({
+    kind: z
+        .enum(["video", "audio", "subtitle"])
+        .describe("Track type to append. video=V2/V3..., audio=A2/A3..., subtitle=ST1..."),
+});
+export function createAddTrackTool(host) {
+    return {
+        name: "add_track",
+        description: "Append an empty track to the active timeline. Useful before insert_broll when V2 " +
+            "doesn't exist yet, or before import_subtitles when no subtitle track exists. " +
+            "Resolve only — Premiere uses File → Sequence → Add Tracks manually.",
+        parameters: AddTrackParams,
+        async execute({ kind }) {
+            try {
+                const r = await host.addTrack(kind);
+                return compact({ ok: true, kind, track: r.track });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=add-track.js.map

package/dist/tools/add-track.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-track.js","sourceRoot":"","sources":["../../src/tools/add-track.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAGjD,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,IAAI,EAAE,CAAC;SACJ,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;SACpC,QAAQ,CAAC,uEAAuE,CAAC;CACrF,CAAC,CAAC;AAEH,MAAM,UAAU,kBAAkB,CAAC,IAAe;IAChD,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,WAAW,EACT,mFAAmF;YACnF,+EAA+E;YAC/E,qEAAqE;QACvE,UAAU,EAAE,cAAc;QAC1B,KAAK,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE;YACpB,IAAI,CAAC;gBACH,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;gBACpC,OAAO,OAAO,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;YACrD,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,OAAO,GAAG,CAAE,CAAW,CAAC,OAAO,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/analyze-hook.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+declare const AnalyzeHookParams: z.ZodObject<{
+    input: z.ZodString;
+    windowSec: z.ZodOptional<z.ZodNumber>;
+    passThreshold: z.ZodOptional<z.ZodNumber>;
+    detail: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        high: "high";
+    }>>;
+    model: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * analyze_hook — does the first 3 seconds earn the scroll-stop?
+ *
+ * Runs four checks and returns a 0-100 score plus a list of issues:
+ *   1. Speech in the first 0.5s   (silencedetect probe)
+ *   2. On-screen text             (vision)
+ *   3. Visual motion              (vision; compares two early frames)
+ *   4. Subject clarity            (vision)
+ *   5. Emotional intensity        (vision)
+ *
+ * The agent's job is to surface the score + findings, then drop a red
+ * marker if the hook fails so the user knows where to recut.
+ */
+export declare function createAnalyzeHookTool(cwd: string): AgentTool<typeof AnalyzeHookParams>;
+export {};
+//# sourceMappingURL=analyze-hook.d.ts.map

package/dist/tools/analyze-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-hook.d.ts","sourceRoot":"","sources":["../../src/tools/analyze-hook.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAOhD,QAAA,MAAM,iBAAiB;;;;;;;;;iBAkBrB,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,iBAAiB,CAAC,CA0FtF"}

package/dist/tools/analyze-hook.js

@@ -0,0 +1,126 @@
+import { resolve as resolvePath } from "node:path";
+import { z } from "zod";
+import { compact, err } from "../core/format.js";
+import { extractAtTimes } from "../core/frames.js";
+import { buildHookResult, runHookVision, speechAt0_5sScore } from "../core/hook-analysis.js";
+import { checkFfmpeg, probeMedia, runFfmpeg } from "../core/media/ffmpeg.js";
+import { parseSilenceDetect } from "../core/silence.js";
+const AnalyzeHookParams = z.object({
+    input: z.string().describe("Source video (relative resolves to cwd)."),
+    windowSec: z
+        .number()
+        .min(0.5)
+        .max(10)
+        .optional()
+        .describe("Window to analyse from t=0. Default 3s — the algorithmic checkpoint for short-form."),
+    passThreshold: z
+        .number()
+        .min(0)
+        .max(100)
+        .optional()
+        .describe("Score (0-100) above which the hook is judged to pass. Default 70."),
+    detail: z.enum(["low", "high"]).optional().describe("Vision detail. Default low."),
+    model: z.string().optional().describe("OpenAI model. Default gpt-4o-mini."),
+});
+/**
+ * analyze_hook — does the first 3 seconds earn the scroll-stop?
+ *
+ * Runs four checks and returns a 0-100 score plus a list of issues:
+ *   1. Speech in the first 0.5s   (silencedetect probe)
+ *   2. On-screen text             (vision)
+ *   3. Visual motion              (vision; compares two early frames)
+ *   4. Subject clarity            (vision)
+ *   5. Emotional intensity        (vision)
+ *
+ * The agent's job is to surface the score + findings, then drop a red
+ * marker if the hook fails so the user knows where to recut.
+ */
+export function createAnalyzeHookTool(cwd) {
+    return {
+        name: "analyze_hook",
+        description: "Score the first 3 seconds of a video for retention (TikTok / Reels / Shorts / YouTube). " +
+            "Returns a 0-100 score and a list of findings (silent open, no on-screen text, static " +
+            "framing, no clear subject, weak emotional hook). The first 2-3 seconds are the " +
+            "algorithmic checkpoint — videos with strong 3-second retention get pushed to larger " +
+            "audiences. ALWAYS check this on short-form before render. If `passes=false`, drop a " +
+            "red PAUSE marker and propose a stronger opener.",
+        parameters: AnalyzeHookParams,
+        async execute(args, ctx) {
+            if (!checkFfmpeg())
+                return err("ffmpeg not on PATH", "install ffmpeg");
+            if (!process.env.OPENAI_API_KEY) {
+                return err("OPENAI_API_KEY not set", "export OPENAI_API_KEY=...");
+            }
+            try {
+                const inAbs = resolvePath(cwd, args.input);
+                const probe = probeMedia(inAbs);
+                if (!probe)
+                    return err(`probe failed for ${inAbs}`, "verify file exists and is media");
+                const windowSec = Math.min(args.windowSec ?? 3, probe.durationSec);
+                if (windowSec < 0.5) {
+                    return err("video shorter than 0.5s — nothing to analyse");
+                }
+                // ── Audio: silencedetect over [0, windowSec] ─────────────────
+                // We accept any silence ≥ 0.05s in this short window — even
+                // brief openings of dead air kill retention.
+                const silenceRun = await runFfmpeg([
+                    "-i",
+                    inAbs,
+                    "-t",
+                    String(windowSec),
+                    "-af",
+                    "silencedetect=noise=-30dB:d=0.05",
+                    "-f",
+                    "null",
+                    "-",
+                ], { signal: ctx.signal });
+                if (silenceRun.code !== 0) {
+                    return err(`silencedetect failed: ${tail(silenceRun.stderr)}`);
+                }
+                const silences = parseSilenceDetect(silenceRun.stderr, windowSec);
+                const speech = speechAt0_5sScore(silences, Math.min(0.5, windowSec));
+                // ── Vision: two frames sampled near the start of the window ──
+                // 0.5s and (windowSec - 0.5) so the model sees opening and
+                // ~end-of-window for motion comparison.
+                const earlyT = Math.min(0.5, windowSec * 0.2);
+                const laterT = Math.max(earlyT + 0.3, windowSec - 0.5);
+                const frames = await extractAtTimes(inAbs, [earlyT, laterT], {
+                    maxWidth: 768,
+                    signal: ctx.signal,
+                });
+                if (frames.length < 2) {
+                    return err("could not extract two frames from the opening window");
+                }
+                const vision = await runHookVision(frames[0].path, frames[1].path, {
+                    detail: args.detail,
+                    model: args.model,
+                    signal: ctx.signal,
+                });
+                const result = buildHookResult(speech, vision, {
+                    passThreshold: args.passThreshold,
+                });
+                return compact({
+                    score: result.score,
+                    passes: result.passes,
+                    findings: result.findings,
+                    why: result.why,
+                    breakdown: {
+                        speechAt0_5s: result.speechAt0_5s,
+                        onScreenText: result.onScreenText,
+                        motion: result.motion,
+                        subjectClarity: result.subjectClarity,
+                        emotionalIntensity: result.emotionalIntensity,
+                    },
+                    windowSec,
+                });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+function tail(s) {
+    return s.split("\n").filter(Boolean).slice(-3).join(" | ").slice(-300);
+}
+//# sourceMappingURL=analyze-hook.js.map

package/dist/tools/analyze-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-hook.js","sourceRoot":"","sources":["../../src/tools/analyze-hook.ts"],"names":[],"mappings":"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"}

package/dist/tools/append-clip.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+import type { VideoHost } from "../core/hosts/types.js";
+declare const AppendClipParams: z.ZodObject<{
+    track: z.ZodNumber;
+    mediaPath: z.ZodString;
+}, z.core.$strip>;
+export declare function createAppendClipTool(host: VideoHost, cwd: string): AgentTool<typeof AppendClipParams>;
+export {};
+//# sourceMappingURL=append-clip.d.ts.map

package/dist/tools/append-clip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"append-clip.d.ts","sourceRoot":"","sources":["../../src/tools/append-clip.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD,QAAA,MAAM,gBAAgB;;;iBAGpB,CAAC;AAEH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,MAAM,GACV,SAAS,CAAC,OAAO,gBAAgB,CAAC,CAkBpC"}

package/dist/tools/append-clip.js

@@ -0,0 +1,27 @@
+import { resolve as resolvePath } from "node:path";
+import { z } from "zod";
+import { compact, err } from "../core/format.js";
+const AppendClipParams = z.object({
+    track: z.number().int().min(1),
+    mediaPath: z.string(),
+});
+export function createAppendClipTool(host, cwd) {
+    return {
+        name: "append_clip",
+        description: "Append a media clip to the end of a track. Most reliable timeline op across both " +
+            "Resolve and Premiere — prefer over move/insert.",
+        parameters: AppendClipParams,
+        async execute({ track, mediaPath }) {
+            try {
+                const abs = resolvePath(cwd, mediaPath);
+                const c = await host.appendClip(track, abs);
+                // Echo only state delta; track/path is already in args.
+                return compact({ id: c.id, start: c.startFrame, end: c.endFrame });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=append-clip.js.map