@kenkaiiii/gg-editor 0.6.7 → 0.7.1

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/audit-first-frame.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import type { AgentTool } from "@kenkaiiii/gg-agent";
+declare const AuditFirstFrameParams: z.ZodObject<{
+    input: z.ZodString;
+    detail: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        high: "high";
+    }>>;
+    model: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface FirstFrameVisionResponse {
+    score: number;
+    hasFace: boolean;
+    faceProminent: boolean;
+    hasReadableText: boolean;
+    hasClearSubject: boolean;
+    hasMotion: boolean;
+    mode: "static-logo" | "cold-open-load" | "face-blink" | "usable" | "strong";
+    findings: string[];
+}
+/**
+ * audit_first_frame — score t=0.0s as if it were the thumbnail.
+ *
+ * Per Hoyos / Galloway: "treat the first frame like a thumbnail."
+ * Autoplay surfaces the first frame BEFORE audio loads, so a logo slate
+ * or cold-open hold tanks retention before viewers ever hear the hook.
+ */
+export declare function createAuditFirstFrameTool(cwd: string): AgentTool<typeof AuditFirstFrameParams>;
+/**
+ * Parse the model's JSON response. Robust to missing keys / weird types
+ * — never throws as long as the JSON itself is valid. Pure — exported
+ * for testing.
+ */
+export declare function parseFirstFrameResponse(content: string): FirstFrameVisionResponse;
+export {};
+//# sourceMappingURL=audit-first-frame.d.ts.map

package/dist/tools/audit-first-frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-first-frame.d.ts","sourceRoot":"","sources":["../../src/tools/audit-first-frame.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAMrD,QAAA,MAAM,qBAAqB;;;;;;;iBAIzB,CAAC;AA+BH,UAAU,wBAAwB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,eAAe,EAAE,OAAO,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,aAAa,GAAG,gBAAgB,GAAG,YAAY,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC5E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,qBAAqB,CAAC,CAmD9F;AAwDD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,wBAAwB,CA6BjF"}

package/dist/tools/audit-first-frame.js

@@ -0,0 +1,181 @@
+import { readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { z } from "zod";
+import { resolveApiKey } from "../core/auth/api-keys.js";
+import { compact, err } from "../core/format.js";
+import { extractAtTimes } from "../core/frames.js";
+import { checkFfmpeg, probeMedia } from "../core/media/ffmpeg.js";
+const AuditFirstFrameParams = z.object({
+    input: z.string().describe("Source video (relative resolves to cwd)."),
+    detail: z.enum(["low", "high"]).optional().describe("Vision detail. Default low."),
+    model: z.string().optional().describe("OpenAI model. Default gpt-4o-mini."),
+});
+const VISION_SYSTEM = `You score a SINGLE FRAME (the first frame of a YouTube video) AS IF it were the thumbnail at 100x56 mobile-feed scale. Autoplay shows this frame BEFORE audio loads — if it looks like a logo slate, a black hold, or a mid-blink face, the viewer scrolls.
+
+Output a JSON object with these EXACT keys:
+{
+  "score":           <0..100 integer>,
+  "hasFace":         <bool>,
+  "faceProminent":   <bool>,         // face fills ≥ ~20% of frame area
+  "hasReadableText": <bool>,         // any large legible text (hook line, label)
+  "hasClearSubject": <bool>,         // a single obvious focal point
+  "hasMotion":       <bool>,         // not strictly possible from one frame; mark true only when blur / streak / mid-action implies motion
+  "mode":            "static-logo"|"cold-open-load"|"face-blink"|"usable"|"strong",
+  "findings":        [<string>, ...] // 1-4 short findings (≤120 chars each)
+}
+
+Scoring rubric:
+  85-100: STRONG — clear subject, expressive face, color contrast, readable text, no logo slate.
+  60-84:  USABLE — subject present, decent contrast, no obvious blockers.
+  30-59:  WEAK — abstract pattern, small subject, soft contrast, mid-blink, or pre-roll filler.
+  0-29:   FAIL — black slate, plain logo card, glitch frame, mid-blink face, totally unreadable.
+
+Modes:
+  static-logo    = a logo card / channel branding slate
+  cold-open-load = a near-black or solid-color frame (intro hasn't started)
+  face-blink     = a face mid-blink / mid-word / awkward expression
+  usable         = nothing wrong but nothing exceptional either
+  strong         = thumbnail-ready opening frame
+
+Be honest — this rubric exists so the creator knows when to recut their first frame.`;
+/**
+ * audit_first_frame — score t=0.0s as if it were the thumbnail.
+ *
+ * Per Hoyos / Galloway: "treat the first frame like a thumbnail."
+ * Autoplay surfaces the first frame BEFORE audio loads, so a logo slate
+ * or cold-open hold tanks retention before viewers ever hear the hook.
+ */
+export function createAuditFirstFrameTool(cwd) {
+    return {
+        name: "audit_first_frame",
+        description: "Score the first frame of a video as if it were the thumbnail at 100×56 mobile-feed " +
+            "scale. Per Galloway / Hoyos: 'treat your intro like a thumbnail' — autoplay shows the " +
+            "first frame BEFORE audio loads, so logo slates and cold-open holds tank retention. " +
+            "Penalises static-logo, cold-open-load, face-blink modes; rewards a clear subject + " +
+            "expressive face + readable hook text. Pair with `audit_retention_structure` and " +
+            "`analyze_hook` as the three short-form pre-render checks. Returns score 0-100 + " +
+            "findings + mode.",
+        parameters: AuditFirstFrameParams,
+        async execute(args, ctx) {
+            if (!checkFfmpeg())
+                return err("ffmpeg not on PATH", "install ffmpeg");
+            const apiKey = resolveApiKey("OPENAI_API_KEY", "openai");
+            if (!apiKey)
+                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 frames = await extractAtTimes(inAbs, [0], {
+                    maxWidth: 768,
+                    signal: ctx.signal,
+                });
+                if (frames.length === 0) {
+                    return err("could not extract first frame", "verify the input is a readable video");
+                }
+                const vision = await runFirstFrameVision(frames[0].path, {
+                    apiKey,
+                    model: args.model,
+                    detail: args.detail,
+                    signal: ctx.signal,
+                });
+                return compact({
+                    score: vision.score,
+                    mode: vision.mode,
+                    hasFace: vision.hasFace,
+                    faceProminent: vision.faceProminent,
+                    hasReadableText: vision.hasReadableText,
+                    hasClearSubject: vision.hasClearSubject,
+                    hasMotion: vision.hasMotion,
+                    findings: vision.findings,
+                });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+async function runFirstFrameVision(framePath, opts) {
+    const b64 = readFileSync(framePath).toString("base64");
+    const detail = opts.detail ?? "low";
+    const model = opts.model ?? "gpt-4o-mini";
+    const body = {
+        model,
+        messages: [
+            { role: "system", content: VISION_SYSTEM },
+            {
+                role: "user",
+                content: [
+                    { type: "text", text: "FIRST FRAME (t=0):" },
+                    {
+                        type: "image_url",
+                        image_url: { url: `data:image/jpeg;base64,${b64}`, detail },
+                    },
+                ],
+            },
+        ],
+        response_format: { type: "json_object" },
+        max_tokens: 2000,
+        temperature: 0,
+    };
+    const res = await fetch("https://api.openai.com/v1/chat/completions", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${opts.apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: opts.signal,
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`OpenAI HTTP ${res.status}: ${text.slice(0, 200)}`);
+    }
+    const data = (await res.json());
+    const content = data.choices[0]?.message?.content;
+    if (!content)
+        throw new Error("audit_first_frame: empty model response");
+    return parseFirstFrameResponse(content);
+}
+/**
+ * Parse the model's JSON response. Robust to missing keys / weird types
+ * — never throws as long as the JSON itself is valid. Pure — exported
+ * for testing.
+ */
+export function parseFirstFrameResponse(content) {
+    const start = content.indexOf("{");
+    const end = content.lastIndexOf("}");
+    if (start < 0 || end < start) {
+        throw new Error("audit_first_frame: no JSON object in response");
+    }
+    const parsed = JSON.parse(content.slice(start, end + 1));
+    const modeRaw = String(parsed.mode ?? "usable");
+    const mode = (["static-logo", "cold-open-load", "face-blink", "usable", "strong"].includes(modeRaw)
+        ? modeRaw
+        : "usable");
+    const findings = Array.isArray(parsed.findings)
+        ? parsed.findings
+            .map((v) => String(v ?? "").slice(0, 200))
+            .filter((v) => v.length > 0)
+            .slice(0, 8)
+        : [];
+    return {
+        score: clampScore(parsed.score),
+        hasFace: Boolean(parsed.hasFace),
+        faceProminent: Boolean(parsed.faceProminent),
+        hasReadableText: Boolean(parsed.hasReadableText),
+        hasClearSubject: Boolean(parsed.hasClearSubject),
+        hasMotion: Boolean(parsed.hasMotion),
+        mode,
+        findings,
+    };
+}
+function clampScore(v) {
+    const n = typeof v === "number" ? v : Number(v);
+    if (!Number.isFinite(n))
+        return 0;
+    return Math.max(0, Math.min(100, Math.round(n)));
+}
+//# sourceMappingURL=audit-first-frame.js.map

package/dist/tools/audit-first-frame.js.map

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

package/dist/tools/audit-retention-structure.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { AgentTool } from "@kenkaiiii/gg-agent";
+declare const AuditRetentionStructureParams: z.ZodObject<{
+    transcript: z.ZodString;
+    durationSec: z.ZodOptional<z.ZodNumber>;
+    checkpoints: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    model: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * audit_retention_structure — long-form retention checkpoint auditor.
+ *
+ * Per MrBeast's documented manual, every ~3 minutes a re-engagement is
+ * required to keep retention from collapsing. This tool builds a 60s
+ * window around each requested checkpoint, asks the LLM to score
+ * whether re-engagement is happening, and reports the weakest one so
+ * the agent knows where to insert b-roll, punch-ins, or a recut.
+ */
+export declare function createAuditRetentionStructureTool(cwd: string): AgentTool<typeof AuditRetentionStructureParams>;
+export {};
+//# sourceMappingURL=audit-retention-structure.d.ts.map

package/dist/tools/audit-retention-structure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-retention-structure.d.ts","sourceRoot":"","sources":["../../src/tools/audit-retention-structure.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAMrD,QAAA,MAAM,6BAA6B;;;;;iBAqBjC,CAAC;AAEH;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAC/C,GAAG,EAAE,MAAM,GACV,SAAS,CAAC,OAAO,6BAA6B,CAAC,CAiEjD"}

package/dist/tools/audit-retention-structure.js

@@ -0,0 +1,95 @@
+import { readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { z } from "zod";
+import { compact, err } from "../core/format.js";
+import { runRetentionAudit } from "../core/retention-structure.js";
+import { parseTranscript } from "../core/whisper.js";
+const AuditRetentionStructureParams = z.object({
+    transcript: z
+        .string()
+        .describe("Path to a transcript JSON written by `transcribe`. Segments required."),
+    durationSec: z
+        .number()
+        .positive()
+        .optional()
+        .describe("Override transcript.durationSec — useful when you trust the ffprobe duration over the " +
+        "transcript's reported one."),
+    checkpoints: z
+        .array(z.number().positive())
+        .optional()
+        .describe("Checkpoints to audit (seconds). Default [180, 360] — the 3-min and 6-min " +
+        "re-engagement marks. For a 12+ min video pass [180, 360, 540, 720]. Each becomes a " +
+        "60s window centred on the timestamp."),
+    model: z.string().optional().describe("OpenAI model. Default gpt-4o-mini."),
+});
+/**
+ * audit_retention_structure — long-form retention checkpoint auditor.
+ *
+ * Per MrBeast's documented manual, every ~3 minutes a re-engagement is
+ * required to keep retention from collapsing. This tool builds a 60s
+ * window around each requested checkpoint, asks the LLM to score
+ * whether re-engagement is happening, and reports the weakest one so
+ * the agent knows where to insert b-roll, punch-ins, or a recut.
+ */
+export function createAuditRetentionStructureTool(cwd) {
+    return {
+        name: "audit_retention_structure",
+        description: "Audit a long-form video transcript for retention checkpoints (3-min, 6-min " +
+            "re-engagements per MrBeast's documented method) and overall escalation pattern. Each " +
+            "checkpoint scored 0-1 with a one-line suggestion when weak. Pair with the " +
+            "youtube-algorithm-primer skill — viewers drop hardest at flat stretches between " +
+            "minutes 1-7. Returns checkpoints[], escalationScore, and weakestCheckpoint so the " +
+            "agent knows where to insert b-roll, punch-ins, or re-cut. Requires `transcribe` first.",
+        parameters: AuditRetentionStructureParams,
+        async execute(args, ctx) {
+            try {
+                if (!process.env.OPENAI_API_KEY) {
+                    return err("OPENAI_API_KEY not set", "export OPENAI_API_KEY=...");
+                }
+                const transcriptAbs = resolvePath(cwd, args.transcript);
+                let raw;
+                try {
+                    raw = readFileSync(transcriptAbs, "utf8");
+                }
+                catch (e) {
+                    return err(`cannot read transcript ${transcriptAbs}: ${e.message}`, "verify the transcript JSON exists");
+                }
+                let t;
+                try {
+                    t = parseTranscript(raw);
+                }
+                catch (e) {
+                    return err(e.message);
+                }
+                if (t.segments.length === 0) {
+                    return err("transcript has no segments", "rerun transcribe(...)");
+                }
+                const totalSec = args.durationSec ?? t.durationSec;
+                if (!totalSec || totalSec <= 0) {
+                    return err("transcript has zero duration", "pass durationSec explicitly");
+                }
+                const result = await runRetentionAudit(t, {
+                    model: args.model,
+                    checkpoints: args.checkpoints,
+                    durationSec: totalSec,
+                    signal: ctx.signal,
+                });
+                return compact({
+                    checkpoints: result.checkpoints.map((c) => ({
+                        atSec: c.atSec,
+                        score: +c.score.toFixed(2),
+                        summary: c.summary,
+                        ...(c.suggestion ? { suggestion: c.suggestion } : {}),
+                    })),
+                    escalationScore: +result.escalationScore.toFixed(2),
+                    overallSummary: result.overallSummary,
+                    weakestCheckpoint: result.weakestCheckpoint,
+                });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=audit-retention-structure.js.map

package/dist/tools/audit-retention-structure.js.map

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

package/dist/tools/audit-retention-structure.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=audit-retention-structure.test.d.ts.map

package/dist/tools/audit-retention-structure.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-retention-structure.test.d.ts","sourceRoot":"","sources":["../../src/tools/audit-retention-structure.test.ts"],"names":[],"mappings":""}