vidspotai-shared 1.0.53 → 1.0.55

package/lib/services/agent/personas.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PersonaRouter = exports.PERSONA_PACKS = exports.AgentPersonaSchema = void 0;
+const zod_1 = require("zod");
+const agentPersona_schema_1 = require("../../schemas/agentPersona.schema");
+Object.defineProperty(exports, "AgentPersonaSchema", { enumerable: true, get: function () { return agentPersona_schema_1.AgentPersonaSchema; } });
+const modelRouter_1 = require("./modelRouter");
+exports.PERSONA_PACKS = {
+    "ugc-ad": {
+        id: "ugc-ad",
+        label: "UGC Ad",
+        blurb: "Hook-first 9:16 ads with creator energy and punchy product reveals.",
+        defaults: {
+            aspect: "9:16",
+            durationSec: 30,
+            tone: "warm",
+            pacing: "fast",
+            hookStyle: "pattern-interrupt",
+            tierBudget: "T2",
+        },
+        plannerPrompt: [
+            "UGC ad rules:",
+            "- First 3s MUST be a problem-statement or pattern-interrupt hook (no logos, no slow b-roll).",
+            "- Cut every 1.5–2.5s after the hook.",
+            "- Voiceover or talking-head drives the script; visuals support, not lead.",
+            "- End with a one-sentence CTA + product name burned in.",
+            "- Avoid medical / unverifiable claims (legal risk).",
+        ].join("\n"),
+        defaultBpm: 110,
+        criticEmphasis: { hookStrength: 0.3, brandSafety: 0.2 },
+    },
+    "faceless-yt": {
+        id: "faceless-yt",
+        label: "Faceless YouTube",
+        blurb: "Educational 16:9 explainers built mostly from cheap stock + voiceover.",
+        defaults: {
+            aspect: "16:9",
+            durationSec: 60,
+            tone: "informational",
+            pacing: "medium",
+            hookStyle: "bold-claim",
+            tierBudget: "T0",
+        },
+        plannerPrompt: [
+            "Faceless YouTube rules:",
+            "- Mostly T0 (stock + Ken Burns) to keep cost <$0.10/video.",
+            "- Hook = counter-intuitive claim or surprising stat in first 8s.",
+            "- Captions burned in; assume sound-off viewing.",
+            "- 1 voiceover line per scene; visuals illustrate the line literally.",
+            "- Avoid copyrighted footage; prefer stock and AI-generated stills.",
+        ].join("\n"),
+        criticEmphasis: { costVsTier: 0.25, voVisualSync: 0.25 },
+    },
+    "product-demo": {
+        id: "product-demo",
+        label: "Product Demo",
+        blurb: "Square e-comm demos with hero shot first and crisp end-cards.",
+        defaults: {
+            aspect: "1:1",
+            durationSec: 20,
+            tone: "energetic",
+            pacing: "fast",
+            hookStyle: "demo",
+            tierBudget: "T2",
+        },
+        plannerPrompt: [
+            "Product demo rules:",
+            "- Hero product shot in first 3s (T2 image-to-video on the hero only).",
+            "- T0 stock or T1 AI image+motion for filler scenes between.",
+            "- Background music ducked under voiceover; no music-only sections.",
+            "- End-card with logo + CTA; aspect MUST match brief (default 1:1).",
+        ].join("\n"),
+        criticEmphasis: { intentMatch: 0.3, brandSafety: 0.15 },
+    },
+    "talking-head": {
+        id: "talking-head",
+        label: "Talking-Head Educator",
+        blurb: "Authority-driven explainers using a presenter avatar + b-roll cutaways.",
+        defaults: {
+            aspect: "16:9",
+            durationSec: 45,
+            tone: "professional",
+            pacing: "medium",
+            hookStyle: "question",
+            tierBudget: "T1",
+        },
+        plannerPrompt: [
+            "Talking-head educator rules:",
+            "- Persona is on-camera (avatar or stock talking-head); cut to b-roll for emphasis only.",
+            "- Open with a question the viewer has googled.",
+            "- One key insight per 10s; recap at end.",
+            "- Prefer T1 (image+motion) for b-roll; T0 stock fallbacks if budget tight.",
+        ].join("\n"),
+        criticEmphasis: { intentMatch: 0.25, voVisualSync: 0.25 },
+    },
+    "social-recap": {
+        id: "social-recap",
+        label: "Social Recap",
+        blurb: "Fast multi-clip recaps for news, sports, listicles — beat-cut energy.",
+        defaults: {
+            aspect: "9:16",
+            durationSec: 30,
+            tone: "energetic",
+            pacing: "very-fast",
+            hookStyle: "stat",
+            tierBudget: "T0",
+        },
+        plannerPrompt: [
+            "Social recap rules:",
+            "- Cuts on the music beat; assume an upbeat track at 110–130 BPM.",
+            "- 1 sentence per clip max; on-screen text mirrors voice.",
+            "- Mostly T0 stock; use AI generation sparingly for transitions.",
+            "- Hook = the most surprising stat or the punchline up front.",
+        ].join("\n"),
+        defaultBpm: 120,
+        criticEmphasis: { pacingFit: 0.3, costVsTier: 0.2 },
+    },
+};
+const RoutedPersonaSchema = zod_1.z.object({
+    persona: agentPersona_schema_1.AgentPersonaSchema,
+    confidence: zod_1.z.number().min(0).max(1),
+    reason: zod_1.z.string(),
+});
+class PersonaRouter {
+    constructor(llm, router = new modelRouter_1.ModelRouter()) {
+        this.llm = llm;
+        this.router = router;
+    }
+    async route(rawPrompt) {
+        const model = this.router.pickFor("router");
+        const personaList = Object.values(exports.PERSONA_PACKS)
+            .map((p) => `- ${p.id}: ${p.blurb}`)
+            .join("\n");
+        const result = await this.llm.structured({
+            model,
+            schema: RoutedPersonaSchema,
+            schemaName: "RoutedPersona",
+            temperature: 0,
+            messages: [
+                {
+                    role: "system",
+                    content: [
+                        "Classify the user's video request into ONE persona.",
+                        "Personas:",
+                        personaList,
+                        "",
+                        "Pick the closest fit. confidence 0..1; reason in <20 words.",
+                    ].join("\n"),
+                },
+                { role: "user", content: rawPrompt },
+            ],
+        });
+        return result.data;
+    }
+}
+exports.PersonaRouter = PersonaRouter;

package/lib/services/agent/planner.d.ts

@@ -0,0 +1,56 @@
+import { AgentPersona } from "../../schemas/agentPersona.schema";
+import { VideoBrief } from "../../schemas/brief.schema";
+import { VideoPlan } from "../../schemas/videoPlan.schema";
+import { IBrandKitModel, IStyleMemoryModel } from "../../models/agent.model";
+import { LlmCaller } from "./llmCaller";
+import { ModelRouter } from "./modelRouter";
+/**
+ * Planner — turns a VideoBrief into a Zod-validated VideoPlan.
+ *
+ * Plan-then-execute architecture (not free-form ReAct): the planner runs in a
+ * single structured-output call, the executor runs the plan, the critic QA's
+ * after. This split is what makes Claude Code reliable and applies the same
+ * shape here.
+ *
+ * Validation strategy: structured-output is enforced at the LLM layer; this
+ * class additionally re-validates against VideoPlanSchema and retries up to
+ * `maxRetries` times feeding the validation errors back as correction context.
+ */
+export interface PlannerOptions {
+    llm: LlmCaller;
+    router?: ModelRouter;
+    maxRetries?: number;
+}
+export declare class Planner {
+    private readonly opts;
+    private readonly router;
+    private readonly maxRetries;
+    constructor(opts: PlannerOptions);
+    plan(brief: VideoBrief, opts?: {
+        persona?: AgentPersona;
+        brandKit?: IBrandKitModel | null;
+        styleMemory?: IStyleMemoryModel | null;
+    }): Promise<VideoPlan>;
+    /**
+     * Streaming variant of `plan()`. Yields raw token chunks from the model so
+     * the host (SSE endpoint) can forward them to the drawer for token-by-token
+     * rendering, then resolves to the validated VideoPlan once the structured
+     * payload is complete. Falls back to a single-shot call (one chunk = full
+     * text) when the LLM caller doesn't implement `structuredStream`.
+     *
+     * Retries are NOT streamed: only the first attempt is exposed to the UI;
+     * if validation fails we re-call `plan()` (non-streaming) and emit the
+     * final retry as a single chunk. Streaming retries would confuse callers
+     * who already painted partial JSON for the first attempt.
+     */
+    planStream(brief: VideoBrief, opts?: {
+        persona?: AgentPersona;
+        brandKit?: IBrandKitModel | null;
+        styleMemory?: IStyleMemoryModel | null;
+    }): {
+        tokens: AsyncIterable<string>;
+        result: Promise<VideoPlan>;
+    };
+    private buildMessages;
+}
+//# sourceMappingURL=planner.d.ts.map

package/lib/services/agent/planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../../src/services/agent/planner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,SAAS,EAAmB,MAAM,gCAAgC,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7E,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,OAAO;IAIN,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAEP,IAAI,EAAE,cAAc;IAK3C,IAAI,CACR,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;QACJ,OAAO,CAAC,EAAE,YAAY,CAAC;QACvB,QAAQ,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;QACjC,WAAW,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;KACnC,GACL,OAAO,CAAC,SAAS,CAAC;IAqCrB;;;;;;;;;;;OAWG;IACH,UAAU,CACR,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE;QACJ,OAAO,CAAC,EAAE,YAAY,CAAC;QACvB,QAAQ,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;QACjC,WAAW,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;KACnC,GACL;QAAE,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAA;KAAE;IA+ChE,OAAO,CAAC,aAAa;CAiFtB"}

package/lib/services/agent/planner.js

@@ -0,0 +1,237 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Planner = void 0;
+const videoPlan_schema_1 = require("../../schemas/videoPlan.schema");
+const tierHelpers_1 = require("../../globals/aiModels/tierHelpers");
+const modelRouter_1 = require("./modelRouter");
+const personas_1 = require("./personas");
+class Planner {
+    constructor(opts) {
+        this.opts = opts;
+        this.router = opts.router ?? new modelRouter_1.ModelRouter();
+        this.maxRetries = opts.maxRetries ?? 2;
+    }
+    async plan(brief, opts = {}) {
+        const model = this.router.pickFor("planner", {
+            premium: brief.tierBudget === "T3",
+        });
+        let lastErrors;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const messages = this.buildMessages(brief, opts.persona, opts.brandKit ?? null, opts.styleMemory ?? null, lastErrors);
+            const result = await this.opts.llm.structured({
+                model,
+                messages,
+                schema: videoPlan_schema_1.VideoPlanSchema,
+                schemaName: "VideoPlan",
+                temperature: attempt === 0 ? 0.4 : 0.2,
+            });
+            // Defense-in-depth: re-validate even though structured() should have.
+            const reparsed = videoPlan_schema_1.VideoPlanSchema.safeParse(result.data);
+            if (reparsed.success)
+                return reparsed.data;
+            lastErrors = reparsed.error.issues
+                .map((i) => `${i.path.join(".")}: ${i.message}`)
+                .join("; ");
+        }
+        throw new Error(`Planner failed to produce a valid VideoPlan after ${this.maxRetries + 1} attempts. Last errors: ${lastErrors}`);
+    }
+    /**
+     * Streaming variant of `plan()`. Yields raw token chunks from the model so
+     * the host (SSE endpoint) can forward them to the drawer for token-by-token
+     * rendering, then resolves to the validated VideoPlan once the structured
+     * payload is complete. Falls back to a single-shot call (one chunk = full
+     * text) when the LLM caller doesn't implement `structuredStream`.
+     *
+     * Retries are NOT streamed: only the first attempt is exposed to the UI;
+     * if validation fails we re-call `plan()` (non-streaming) and emit the
+     * final retry as a single chunk. Streaming retries would confuse callers
+     * who already painted partial JSON for the first attempt.
+     */
+    planStream(brief, opts = {}) {
+        const model = this.router.pickFor("planner", {
+            premium: brief.tierBudget === "T3",
+        });
+        const messages = this.buildMessages(brief, opts.persona, opts.brandKit ?? null, opts.styleMemory ?? null);
+        if (!this.opts.llm.structuredStream) {
+            // Fallback path — emit the whole plan as one chunk after non-streaming call.
+            const result = this.plan(brief, opts);
+            const tokens = {
+                async *[Symbol.asyncIterator]() {
+                    const plan = await result;
+                    yield JSON.stringify(plan);
+                },
+            };
+            return { tokens, result };
+        }
+        const stream = this.opts.llm.structuredStream({
+            model,
+            messages,
+            schema: videoPlan_schema_1.VideoPlanSchema,
+            schemaName: "VideoPlan",
+            temperature: 0.4,
+        });
+        const planner = this;
+        const result = (async () => {
+            try {
+                const r = await stream.result;
+                const reparsed = videoPlan_schema_1.VideoPlanSchema.safeParse(r.data);
+                if (reparsed.success)
+                    return reparsed.data;
+                // Validation tripped on a streamed payload — fall back to retry pass.
+                return planner.plan(brief, opts);
+            }
+            catch {
+                return planner.plan(brief, opts);
+            }
+        })();
+        return { tokens: stream.tokens, result };
+    }
+    buildMessages(brief, persona, brandKit, styleMemory, lastErrors) {
+        const personaSection = persona
+            ? [
+                "",
+                `Selected persona: ${persona}.`,
+                `Set plan.persona to "${persona}" in the output.`,
+                "Persona-specific structural rules (apply on top of the global tier rules):",
+                personas_1.PERSONA_PACKS[persona].plannerPrompt,
+            ].join("\n")
+            : "";
+        const brandKitSection = buildBrandKitSection(brandKit);
+        const styleMemorySection = buildStyleMemorySection(styleMemory);
+        const modelCatalogSection = buildModelCatalogSection();
+        const system = [
+            "You are a video-production planner.",
+            "Given a VideoBrief, produce a VideoPlan: an ordered list of scenes",
+            "with per-scene asset strategy, tier, prompt, duration, and voiceover.",
+            "",
+            "Tier rules — respect brief.tierBudget as the maximum tier:",
+            "  T0: stock footage / image with Ken-Burns motion.",
+            "  T1: AI-generated still + camera motion.",
+            "  T2: AI image-to-video on key frames only.",
+            "  T3: full text-to-video (most expensive — use sparingly).",
+            "",
+            "talking-head-avatar is wired and runs the kling-avatar pipeline (face",
+            "still + TTS lipsync). Pick it ONLY when the brand kit exposes a",
+            "presenterFaceUrl — set scene.avatarFaceUrl to that URL on every avatar",
+            "scene. If no presenter face is available, fall back to ai-image-to-video",
+            "or stock-video of a presenter instead.",
+            "",
+            "user-asset is wired and reuses the requesting user's existing library",
+            "(their previously generated images / videos / audio) instead of spending",
+            "credits to make a new asset. Pick user-asset when the brief mentions a",
+            "recurring brand subject (their product photo, spokesperson, b-roll) —",
+            "the executor falls back to stock-video if no library match scores high",
+            "enough, so picking it is safe.",
+            "",
+            "Keep total estimated credits as low as possible while honoring the",
+            "brief. Mix tiers within a single video where it helps cost without",
+            "harming quality (e.g. T2 hero shot + T0 b-roll between).",
+            "",
+            "Smart model routing — set preferredModel per scene from the catalog:",
+            "  - Hero / opening-hook / product-reveal scenes: pick the highest-",
+            "    quality model in the chosen tier (most expensive in that tier).",
+            "  - B-roll / filler / transition scenes: pick the cheapest model in",
+            "    the chosen tier — the audience won't notice the difference and",
+            "    cost drops 3–5x.",
+            "  - When in doubt for a non-hero scene, pick the median-cost model.",
+            "  - preferredModel must match a key from the catalog below; the",
+            "    executor will swap on rate-limit, so picking is best-effort, not",
+            "    a hard contract.",
+            modelCatalogSection,
+            personaSection,
+            brandKitSection,
+            styleMemorySection,
+        ]
+            .filter(Boolean)
+            .join("\n");
+        const user = [
+            `Brief:\n${JSON.stringify(brief, null, 2)}`,
+            lastErrors
+                ? `\nYour previous attempt failed validation: ${lastErrors}\nFix the structure and try again.`
+                : "",
+        ]
+            .filter(Boolean)
+            .join("\n");
+        return [
+            { role: "system", content: system },
+            { role: "user", content: user },
+        ];
+    }
+}
+exports.Planner = Planner;
+function buildModelCatalogSection() {
+    // Today the agent ships text-to-video and image-to-video providers; both
+    // share the same per-tier shape, and t2v is the most common executor path.
+    // Image-gen models live under a separate tool (generate_image) so they
+    // don't belong in this catalog.
+    const t2v = (0, tierHelpers_1.summarizeModelsForPlanner)("text-to-video");
+    const i2v = (0, tierHelpers_1.summarizeModelsForPlanner)("image-to-video");
+    const sections = [];
+    if (t2v)
+        sections.push("", "Text-to-video models by tier (cheapest first):", t2v);
+    if (i2v)
+        sections.push("", "Image-to-video models by tier (cheapest first):", i2v);
+    return sections.join("\n");
+}
+function buildBrandKitSection(brandKit) {
+    if (!brandKit)
+        return "";
+    const lines = [];
+    if (brandKit.brandName)
+        lines.push(`  Brand: ${brandKit.brandName}`);
+    if (brandKit.primaryColorHex || brandKit.secondaryColorHex) {
+        const palette = [brandKit.primaryColorHex, brandKit.secondaryColorHex]
+            .filter(Boolean)
+            .join(" / ");
+        lines.push(`  Palette: ${palette}`);
+    }
+    if (brandKit.fontFamily)
+        lines.push(`  Font: ${brandKit.fontFamily}`);
+    if (brandKit.voiceId)
+        lines.push(`  Preferred TTS voice id: ${brandKit.voiceId}`);
+    if (brandKit.presenterFaceUrl) {
+        lines.push(`  Presenter face URL (use as scene.avatarFaceUrl on talking-head-avatar scenes): ${brandKit.presenterFaceUrl}`);
+    }
+    if (brandKit.musicMoods?.length) {
+        lines.push(`  Music moods: ${brandKit.musicMoods.join(", ")}`);
+    }
+    if (brandKit.preferredClaims?.length) {
+        lines.push(`  Preferred phrasing: ${brandKit.preferredClaims.join("; ")}`);
+    }
+    if (brandKit.bannedClaims?.length) {
+        lines.push(`  NEVER produce these phrases: ${brandKit.bannedClaims.join("; ")}`);
+    }
+    if (!lines.length)
+        return "";
+    return [
+        "",
+        "Brand kit (set once by the user — apply on every scene):",
+        ...lines,
+    ].join("\n");
+}
+function buildStyleMemorySection(memory) {
+    if (!memory)
+        return "";
+    const accepted = (memory.acceptedScenes ?? []).slice(-3);
+    const rejected = (memory.rejectedScenes ?? []).slice(-3);
+    if (!accepted.length && !rejected.length)
+        return "";
+    const fmt = (entry) => {
+        try {
+            return JSON.stringify(entry.scene);
+        }
+        catch {
+            return "[unserializable scene]";
+        }
+    };
+    const sections = ["", "Style memory (recent decisions by this user):"];
+    if (accepted.length) {
+        sections.push("  Bias toward shapes like these (accepted):");
+        accepted.forEach((s) => sections.push(`    - ${fmt(s)}`));
+    }
+    if (rejected.length) {
+        sections.push("  Avoid shapes like these (rejected):");
+        rejected.forEach((s) => sections.push(`    - ${fmt(s)}`));
+    }
+    return sections.join("\n");
+}

package/lib/services/agent/toolRegistry.d.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+/**
+ * MCP-shaped tool registry.
+ *
+ * Tools are defined once here and consumed in two ways:
+ *   1. Internally by the agent (planner/executor/critic) via `getTool(name)`
+ *      and `runTool(name, input)` — no network hop.
+ *   2. Externally as an MCP server endpoint, by reading `listTools()` and
+ *      JSON-RPC dispatching to `runTool` (wired in a later commit).
+ *
+ * Each tool ships with:
+ *   - name: stable identifier the LLM uses
+ *   - description: written for LLMs (when to use, when NOT to use, examples)
+ *   - inputSchema / outputSchema: Zod, validated on every call
+ *   - handler: pure async function over validated input → validated output
+ *
+ * Idempotency, cost preflight, and rate limiting are implemented as wrappers
+ * around `runTool` rather than per-tool, so we don't repeat ourselves.
+ */
+export interface ToolDefinition<I extends z.ZodTypeAny, O extends z.ZodTypeAny> {
+    name: string;
+    description: string;
+    inputSchema: I;
+    outputSchema: O;
+    handler: (input: z.infer<I>, ctx: ToolContext) => Promise<z.infer<O>>;
+    /** If true, identical (name, idempotencyKey) calls return cached result. */
+    idempotent?: boolean;
+    /** Tier-aware cost estimate; called when input.dry_run is true. */
+    estimateCost?: (input: z.infer<I>) => Promise<number>;
+}
+export interface ToolContext {
+    /** User the agent is acting on behalf of. */
+    userId: string;
+    /** Agent run id, for tracing and replay. */
+    agentRunId: string;
+    /** Project the tool is operating on, if applicable. */
+    projectId?: string;
+    /** Idempotency key for generation tools. */
+    idempotencyKey?: string;
+    /** Trace logger; replaced with structured logger by the host. */
+    log?: (event: string, data?: Record<string, unknown>) => void;
+}
+export interface ToolResult<O = unknown> {
+    ok: true;
+    output: O;
+    durationMs: number;
+}
+export interface ToolError {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+    durationMs: number;
+}
+export type ToolOutcome<O = unknown> = ToolResult<O> | ToolError;
+export declare function registerTool<I extends z.ZodTypeAny, O extends z.ZodTypeAny>(def: ToolDefinition<I, O>): void;
+export declare function getTool(name: string): ToolDefinition<z.ZodTypeAny, z.ZodTypeAny> | undefined;
+export declare function listTools(): ToolDefinition<z.ZodTypeAny, z.ZodTypeAny>[];
+/** Execute a tool by name with structured validation + error wrapping. */
+export declare function runTool<O = unknown>(name: string, rawInput: unknown, ctx: ToolContext): Promise<ToolOutcome<O>>;
+/** Test-only: drop all registered tools. */
+export declare function _clearToolsForTesting(): void;
+//# sourceMappingURL=toolRegistry.d.ts.map

package/lib/services/agent/toolRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolRegistry.d.ts","sourceRoot":"","sources":["../../../src/services/agent/toolRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,CAAC,SAAS,CAAC,CAAC,UAAU;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC;IACf,YAAY,EAAE,CAAC,CAAC;IAChB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACtE,4EAA4E;IAC5E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,mEAAmE;IACnE,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAC/D;AAED,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE,CAAC,CAAC;IACV,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;AAIjE,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,CAAC,SAAS,CAAC,CAAC,UAAU,EACzE,GAAG,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GACxB,IAAI,CAKN;AAED,wBAAgB,OAAO,CACrB,IAAI,EAAE,MAAM,GACX,cAAc,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,SAAS,CAExD;AAED,wBAAgB,SAAS,IAAI,cAAc,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,UAAU,CAAC,EAAE,CAExE;AAED,0EAA0E;AAC1E,wBAAsB,OAAO,CAAC,CAAC,GAAG,OAAO,EACvC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,OAAO,EACjB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAqDzB;AAED,4CAA4C;AAC5C,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C"}

package/lib/services/agent/toolRegistry.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTool = registerTool;
+exports.getTool = getTool;
+exports.listTools = listTools;
+exports.runTool = runTool;
+exports._clearToolsForTesting = _clearToolsForTesting;
+const tools = new Map();
+function registerTool(def) {
+    if (tools.has(def.name)) {
+        throw new Error(`Tool already registered: ${def.name}`);
+    }
+    tools.set(def.name, def);
+}
+function getTool(name) {
+    return tools.get(name);
+}
+function listTools() {
+    return Array.from(tools.values());
+}
+/** Execute a tool by name with structured validation + error wrapping. */
+async function runTool(name, rawInput, ctx) {
+    const start = Date.now();
+    const tool = tools.get(name);
+    if (!tool) {
+        return {
+            ok: false,
+            error: { code: "TOOL_NOT_FOUND", message: `Unknown tool: ${name}` },
+            durationMs: Date.now() - start,
+        };
+    }
+    const parsed = tool.inputSchema.safeParse(rawInput);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            error: {
+                code: "INPUT_INVALID",
+                message: parsed.error.issues
+                    .map((i) => `${i.path.join(".")}: ${i.message}`)
+                    .join("; "),
+            },
+            durationMs: Date.now() - start,
+        };
+    }
+    try {
+        const output = await tool.handler(parsed.data, ctx);
+        const validatedOutput = tool.outputSchema.safeParse(output);
+        if (!validatedOutput.success) {
+            return {
+                ok: false,
+                error: {
+                    code: "OUTPUT_INVALID",
+                    message: `Tool ${name} returned malformed output: ${validatedOutput.error.message}`,
+                },
+                durationMs: Date.now() - start,
+            };
+        }
+        return {
+            ok: true,
+            output: validatedOutput.data,
+            durationMs: Date.now() - start,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: {
+                code: "TOOL_THREW",
+                message: err instanceof Error ? err.message : String(err),
+            },
+            durationMs: Date.now() - start,
+        };
+    }
+}
+/** Test-only: drop all registered tools. */
+function _clearToolsForTesting() {
+    tools.clear();
+}

package/lib/services/agent/tools/analyzeReference.tool.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { ToolDefinition } from "../toolRegistry";
+/**
+ * Reference grounding — single highest-leverage accuracy multiplier.
+ *
+ * Pulls a TikTok / IG / YT video URL, runs scene detection + transcript +
+ * beat detection, returns structural features the planner can use as priors:
+ * pacing (cuts/sec), hook structure (where the first cut lands), shot count,
+ * music tempo, transcript excerpt.
+ *
+ * Heavy lifting (download, ffmpeg, scene detection) is host-side. Tool layer
+ * is host-agnostic, so the host wires the analyzer fn at boot.
+ */
+export type ReferenceAnalyzerFn = (url: string) => Promise<{
+    durationMs: number;
+    sceneCount: number;
+    hookMs: number;
+    cutsPerSecond: number;
+    bpm?: number;
+    transcriptExcerpt?: string;
+}>;
+export declare function setReferenceAnalyzer(fn: ReferenceAnalyzerFn): void;
+declare const InputSchema: z.ZodObject<{
+    url: z.ZodString;
+}, z.core.$strip>;
+declare const OutputSchema: z.ZodObject<{
+    durationMs: z.ZodNumber;
+    sceneCount: z.ZodNumber;
+    hookMs: z.ZodNumber;
+    cutsPerSecond: z.ZodNumber;
+    bpm: z.ZodOptional<z.ZodNumber>;
+    transcriptExcerpt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const analyzeReferenceTool: ToolDefinition<typeof InputSchema, typeof OutputSchema>;
+export {};
+//# sourceMappingURL=analyzeReference.tool.d.ts.map

package/lib/services/agent/tools/analyzeReference.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzeReference.tool.d.ts","sourceRoot":"","sources":["../../../../src/services/agent/tools/analyzeReference.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAgB,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE/D;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC,CAAC;AAGH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,mBAAmB,GAAG,IAAI,CAElE;AAED,QAAA,MAAM,WAAW;;iBAKf,CAAC;AAEH,QAAA,MAAM,YAAY;;;;;;;iBAOhB,CAAC;AAEH,eAAO,MAAM,oBAAoB,EAAE,cAAc,CAC/C,OAAO,WAAW,EAClB,OAAO,YAAY,CAqBpB,CAAC"}