vidspotai-shared 1.0.67 → 1.0.69-dev.0

package/lib/services/agent/globalActions.js

@@ -0,0 +1,328 @@
+"use strict";
+/**
+ * Session K (Stage 7) — global project-level regen actions.
+ *
+ * Pairs with `AgentRegenTargetSchema.kind === "global"`. The worker dispatches
+ * here instead of through `executeRegenTarget` (which is per-scene / per-
+ * component) because these actions mutate project-wide state:
+ *
+ *   - "soften-music"    — drop volume + mood + bpm, refetch a mellower track
+ *                         via selectMusicForPlan, swap the "music" clip src.
+ *   - "add-cta"         — bias the closing scene's overlays toward a strong
+ *                         CTA via planner.regenerateOverlaysForScene; splice
+ *                         new overlay clips on top of the existing visual.
+ *   - "switch-persona"  — re-run Planner.plan() with the new persona. Project
+ *                         status reverts to "planned" — visuals are stale
+ *                         relative to the new plan, the user must /execute
+ *                         again. projectJson is left intact for inspection.
+ *
+ * Pure logic; never touches Firestore. Caller persists the returned
+ * `projectPatch` as one merge update.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateGlobalActionCost = estimateGlobalActionCost;
+exports.executeGlobalAction = executeGlobalAction;
+const zod_1 = require("zod");
+const agentPersona_schema_1 = require("../../schemas/agentPersona.schema");
+const pricing_1 = require("../credits/pricing");
+const musicSelect_1 = require("./musicSelect");
+const planner_1 = require("./planner");
+const llmCallerRegistry_1 = require("./llmCallerRegistry");
+const planToProject_1 = require("../editor/planToProject");
+const personas_1 = require("./personas");
+const logger_1 = require("../../utils/logger");
+const isoNow = () => new Date().toISOString();
+const AddCtaParamsSchema = zod_1.z.object({
+    ctaText: zod_1.z.string().min(1).max(60).optional(),
+});
+const SwitchPersonaParamsSchema = zod_1.z.object({
+    persona: agentPersona_schema_1.AgentPersonaSchema,
+});
+/**
+ * Per-action cost estimate. Mirrors what `estimateRegenCost` does for the
+ * per-component path so the controller's pre-flight preview and the
+ * worker's refund-on-failure path agree on a number.
+ */
+function estimateGlobalActionCost(action, _params) {
+    switch (action) {
+        case "soften-music":
+            // Music search is free; same cost as a /regenerate-music call.
+            return (0, pricing_1.estimateRegenCost)({ component: "music" });
+        case "add-cta":
+            // One planner LLM call + overlay splice — same as overlays regen.
+            return (0, pricing_1.estimateRegenCost)({ component: "overlays" });
+        case "switch-persona": {
+            // Full re-plan: a single mid-sized planner LLM call (no executor
+            // spend, no provider calls). Flat $0.12 ≈ 12 credits keeps the
+            // budget-guard meaningful without forcing a confirmation modal for
+            // what is just an LLM call. Cost goes up the next time the user
+            // /executes against the new plan — those scenes go through the
+            // normal per-scene credit deduct.
+            const amountUsd = 0.12;
+            return {
+                component: "overlays",
+                amountUsd,
+                amountCredits: Math.ceil(amountUsd * pricing_1.CREDITS_PER_USD),
+                breakdown: { planner: amountUsd },
+                exceedsBudgetGuard: amountUsd > pricing_1.BUDGET_GUARD_THRESHOLD_USD,
+                budgetGuardThresholdUsd: pricing_1.BUDGET_GUARD_THRESHOLD_USD,
+            };
+        }
+    }
+}
+async function executeGlobalAction(action, params, project, _ctx) {
+    const plan = project.plan;
+    if (!plan)
+        return { ok: false, status: 422, error: "plan required" };
+    switch (action) {
+        case "soften-music": {
+            const currentProjectJson = project.projectJson;
+            if (!currentProjectJson) {
+                return {
+                    ok: false,
+                    status: 409,
+                    error: "project not yet rendered — run /execute first",
+                };
+            }
+            const personaPack = personas_1.PERSONA_PACKS[plan.persona];
+            const baseBpm = plan.music?.bpm ?? personaPack?.defaultBpm ?? 100;
+            const softenedBpm = Math.max(60, Math.round(baseBpm * 0.75));
+            const planForReselect = {
+                ...plan,
+                music: {
+                    strategy: plan.music?.strategy ?? "stock-track",
+                    query: plan.music?.query ?? "calm ambient background instrumental",
+                    moodTag: "mellow",
+                    bpm: softenedBpm,
+                    // Force reselect — drop everything the selector previously filled.
+                    url: undefined,
+                    durationSec: undefined,
+                    source: undefined,
+                    attribution: undefined,
+                    onsets: undefined,
+                },
+            };
+            let refreshedPlan;
+            try {
+                refreshedPlan = await (0, musicSelect_1.selectMusicForPlan)(planForReselect);
+            }
+            catch (err) {
+                logger_1.logger.error("globalActions: soften-music failed", {
+                    projectId: _ctx.projectId,
+                    userId: _ctx.userId,
+                    err: err instanceof Error ? err.stack ?? err.message : String(err),
+                });
+                return { ok: false, status: 502, error: err.message };
+            }
+            const newMusicUrl = refreshedPlan.music?.url;
+            const existingMusic = currentProjectJson.clips.find((c) => c.id === "music");
+            let updatedClips;
+            if (newMusicUrl && existingMusic) {
+                updatedClips = currentProjectJson.clips.map((c) => {
+                    if (c.id !== "music")
+                        return c;
+                    const patched = {
+                        ...c,
+                        src: newMusicUrl,
+                        provenance: {
+                            ...(c.provenance ?? {}),
+                            source: refreshedPlan.music?.source ?? "music",
+                            regeneratedAt: isoNow(),
+                            softenedFromBpm: baseBpm,
+                        },
+                    };
+                    return patched;
+                });
+            }
+            else if (!newMusicUrl && existingMusic) {
+                updatedClips = currentProjectJson.clips.filter((c) => c.id !== "music");
+            }
+            else {
+                updatedClips = currentProjectJson.clips;
+            }
+            const cost = estimateGlobalActionCost("soften-music");
+            const baseProject = {
+                ...currentProjectJson,
+                clips: updatedClips,
+                updatedAt: isoNow(),
+            };
+            const nextProjectJson = (0, pricing_1.appendRegenHistory)(baseProject, {
+                ts: isoNow(),
+                action: "regenerate",
+                component: "music",
+                estimatedCreditsSpent: cost.amountCredits,
+                estimatedUsd: cost.amountUsd,
+            });
+            return {
+                ok: true,
+                projectPatch: {
+                    plan: refreshedPlan,
+                    projectJson: nextProjectJson,
+                    updatedAt: isoNow(),
+                },
+                cost,
+                details: {
+                    previousBpm: baseBpm,
+                    newBpm: refreshedPlan.music?.bpm ?? softenedBpm,
+                    musicUrl: newMusicUrl ?? null,
+                },
+            };
+        }
+        case "add-cta": {
+            if (!project.brief) {
+                return { ok: false, status: 422, error: "brief required" };
+            }
+            const currentProjectJson = project.projectJson;
+            if (!currentProjectJson) {
+                return {
+                    ok: false,
+                    status: 409,
+                    error: "project not yet rendered — run /execute first",
+                };
+            }
+            const lastIndex = plan.scenes.length - 1;
+            const closingScene = plan.scenes[lastIndex];
+            const parsedParams = AddCtaParamsSchema.safeParse(params ?? {});
+            const ctaText = parsedParams.success
+                ? parsedParams.data.ctaText
+                : undefined;
+            const instruction = ctaText
+                ? `Add a strong closing CTA. Use the verbatim CTA copy "${ctaText}" (role=cta, max 5 words). Preserve any existing watermark overlay; replace headline / body if needed to make space.`
+                : `Add a strong closing CTA overlay (role=cta, brand + verb, max 5 words). Preserve any existing watermark overlay; replace headline / body if needed to make space.`;
+            const planner = new planner_1.Planner({ llm: (0, llmCallerRegistry_1.getLlmCaller)() });
+            let newOverlays;
+            try {
+                newOverlays = await planner.regenerateOverlaysForScene(closingScene, project.brief, {
+                    persona: plan.persona,
+                    bible: plan.bible,
+                    isClosingScene: true,
+                    instruction,
+                });
+            }
+            catch (err) {
+                logger_1.logger.error("globalActions: add-cta failed", {
+                    projectId: _ctx.projectId,
+                    userId: _ctx.userId,
+                    sceneIndex: lastIndex,
+                    err: err instanceof Error ? err.stack ?? err.message : String(err),
+                });
+                return { ok: false, status: 502, error: err.message };
+            }
+            // Splice new overlay clips for the closing scene. Mirrors the
+            // overlays-regen path in regenCore.
+            const visualClip = currentProjectJson.clips.find((c) => c.id === `scene-${lastIndex}-visual`);
+            const offsetMs = visualClip?.display?.from ?? 0;
+            const sceneDurationMs = visualClip?.display
+                ? visualClip.display.to - visualClip.display.from
+                : closingScene.durationMs;
+            const replacementClips = (0, planToProject_1.buildOverlayClipsForScene)(lastIndex, offsetMs, sceneDurationMs, newOverlays, currentProjectJson.size.height);
+            const overlayPrefix = `scene-${lastIndex}-overlay-`;
+            const survivors = currentProjectJson.clips.filter((c) => !c.id.startsWith(overlayPrefix));
+            const updatedClips = [...survivors, ...replacementClips];
+            const cost = estimateGlobalActionCost("add-cta");
+            const baseProject = {
+                ...currentProjectJson,
+                clips: updatedClips,
+                updatedAt: isoNow(),
+            };
+            const nextProjectJson = (0, pricing_1.appendRegenHistory)(baseProject, {
+                ts: isoNow(),
+                action: "regenerate",
+                component: "overlays",
+                sceneIndex: lastIndex,
+                estimatedCreditsSpent: cost.amountCredits,
+                estimatedUsd: cost.amountUsd,
+            });
+            const nextPlan = {
+                ...plan,
+                scenes: plan.scenes.map((s) => s.sceneIndex === lastIndex ? { ...s, overlays: newOverlays } : s),
+            };
+            return {
+                ok: true,
+                projectPatch: {
+                    plan: nextPlan,
+                    projectJson: nextProjectJson,
+                    updatedAt: isoNow(),
+                },
+                cost,
+                details: {
+                    sceneIndex: lastIndex,
+                    overlayCount: newOverlays.length,
+                    ctaTextOverride: ctaText ?? null,
+                },
+            };
+        }
+        case "switch-persona": {
+            if (!project.brief) {
+                return { ok: false, status: 422, error: "brief required" };
+            }
+            const parsedParams = SwitchPersonaParamsSchema.safeParse(params ?? {});
+            if (!parsedParams.success) {
+                return {
+                    ok: false,
+                    status: 400,
+                    error: "switch-persona requires params.persona (AgentPersona enum)",
+                };
+            }
+            const newPersona = parsedParams.data.persona;
+            if (newPersona === plan.persona) {
+                return {
+                    ok: false,
+                    status: 422,
+                    error: `persona already set to "${newPersona}"`,
+                };
+            }
+            const planner = new planner_1.Planner({ llm: (0, llmCallerRegistry_1.getLlmCaller)() });
+            let newPlanRaw;
+            try {
+                newPlanRaw = await planner.plan(project.brief, {
+                    persona: newPersona,
+                    bible: plan.bible ?? null,
+                });
+            }
+            catch (err) {
+                logger_1.logger.error("globalActions: switch-persona failed", {
+                    projectId: _ctx.projectId,
+                    userId: _ctx.userId,
+                    newPersona,
+                    err: err instanceof Error ? err.stack ?? err.message : String(err),
+                });
+                return { ok: false, status: 502, error: err.message };
+            }
+            // Mirror plan.controller.ts: run music select after replan so the new
+            // plan ships with a track URL ready for the next /execute. Best-effort
+            // — if it throws we still keep the new plan and let the user soften /
+            // regenerate music separately.
+            let newPlan = newPlanRaw;
+            try {
+                newPlan = await (0, musicSelect_1.selectMusicForPlan)(newPlanRaw);
+            }
+            catch (err) {
+                // intentional: music selection is enhancement, not blocking.
+                logger_1.logger.warn("globalActions: selectMusicForPlan failed (non-blocking)", {
+                    projectId: _ctx.projectId,
+                    err: err instanceof Error ? err.stack ?? err.message : String(err),
+                });
+            }
+            const cost = estimateGlobalActionCost("switch-persona");
+            // Visuals are stale relative to the new plan. Revert project status to
+            // "planned" so the UI prompts the user to /execute against the new
+            // plan. projectJson left intact for diff inspection / rollback.
+            return {
+                ok: true,
+                projectPatch: {
+                    plan: newPlan,
+                    persona: newPersona,
+                    status: "planned",
+                    updatedAt: isoNow(),
+                },
+                cost,
+                details: {
+                    previousPersona: plan.persona,
+                    newPersona,
+                    newSceneCount: newPlan.scenes.length,
+                },
+            };
+        }
+    }
+}

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

@@ -0,0 +1,38 @@
+export * from "./toolRegistry";
+export * from "./tools";
+export * from "./modelRouter";
+export * from "./llmCaller";
+export * from "./llmCallerGateway";
+export * from "./llmCallerAnthropic";
+export * from "./personas";
+export * from "./llmCallerRegistry";
+export * from "./costPreflight";
+export * from "./planner";
+export * from "./planMutations";
+export * from "./bibleBuilder";
+export * from "./referenceImageRenderer";
+export * from "./bibleImageVision";
+export * from "./sceneLayoutVision";
+export * from "./beatSnap";
+export * from "./musicSelect";
+export * from "./executor";
+export * from "./providerTaskCache";
+export * from "./planDiff";
+export * from "./taskPoller";
+export * from "./critic";
+export * from "./eval";
+export * from "./providerFallback/chains";
+export * from "./stitchedVideoCritic";
+export * from "./stitchedVideoCritic.gemini";
+export * from "./perSceneCritic";
+export * from "./textOverlayStyles";
+export * from "./overlayRenderer";
+export * from "./editClassifier";
+export * from "./qualityGate";
+export * from "./ttsDuration";
+export * from "./modelQualityNotes";
+export * from "./runHelpers";
+export * from "./regenCore";
+export * from "./globalActions";
+export * from "./chatAgent";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/agent/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC"}

package/lib/services/agent/index.js

@@ -0,0 +1,53 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./toolRegistry"), exports);
+__exportStar(require("./tools"), exports);
+__exportStar(require("./modelRouter"), exports);
+__exportStar(require("./llmCaller"), exports);
+__exportStar(require("./llmCallerGateway"), exports);
+__exportStar(require("./llmCallerAnthropic"), exports);
+__exportStar(require("./personas"), exports);
+__exportStar(require("./llmCallerRegistry"), exports);
+__exportStar(require("./costPreflight"), exports);
+__exportStar(require("./planner"), exports);
+__exportStar(require("./planMutations"), exports);
+__exportStar(require("./bibleBuilder"), exports);
+__exportStar(require("./referenceImageRenderer"), exports);
+__exportStar(require("./bibleImageVision"), exports);
+__exportStar(require("./sceneLayoutVision"), exports);
+__exportStar(require("./beatSnap"), exports);
+__exportStar(require("./musicSelect"), exports);
+__exportStar(require("./executor"), exports);
+__exportStar(require("./providerTaskCache"), exports);
+__exportStar(require("./planDiff"), exports);
+__exportStar(require("./taskPoller"), exports);
+__exportStar(require("./critic"), exports);
+__exportStar(require("./eval"), exports);
+__exportStar(require("./providerFallback/chains"), exports);
+__exportStar(require("./stitchedVideoCritic"), exports);
+__exportStar(require("./stitchedVideoCritic.gemini"), exports);
+__exportStar(require("./perSceneCritic"), exports);
+__exportStar(require("./textOverlayStyles"), exports);
+__exportStar(require("./overlayRenderer"), exports);
+__exportStar(require("./editClassifier"), exports);
+__exportStar(require("./qualityGate"), exports);
+__exportStar(require("./ttsDuration"), exports);
+__exportStar(require("./modelQualityNotes"), exports);
+__exportStar(require("./runHelpers"), exports);
+__exportStar(require("./regenCore"), exports);
+__exportStar(require("./globalActions"), exports);
+__exportStar(require("./chatAgent"), exports);

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

@@ -0,0 +1,144 @@
+import { z } from "zod";
+import { ModelChoice } from "./modelRouter";
+/**
+ * Provider-agnostic LLM caller. The host (Express server / Firebase Functions)
+ * wires a concrete implementation backed by Vercel AI Gateway, OpenRouter, or
+ * direct SDKs. Agent code only ever sees this interface, which keeps it
+ * portable and lets us A/B-test models against the eval set without code changes.
+ */
+export interface LlmCaller {
+    /** Free-form chat completion. */
+    chat(req: ChatRequest): Promise<ChatResponse>;
+    /** Structured-output completion: result is validated against the provided Zod schema. */
+    structured<T extends z.ZodTypeAny>(req: StructuredRequest<T>): Promise<StructuredResponse<T>>;
+    /**
+     * Streaming structured completion. Returns an async iterable of raw text
+     * chunks AND a final promise that resolves to the validated structured
+     * response. Callers typically forward the chunks to a UI channel (SSE)
+     * for token-by-token rendering and await `result` for the parsed payload.
+     *
+     * Implementations that don't natively support streaming may fall back to
+     * a single chunk emission of the full text — the contract is unchanged.
+     */
+    structuredStream?<T extends z.ZodTypeAny>(req: StructuredRequest<T>): {
+        tokens: AsyncIterable<string>;
+        result: Promise<StructuredResponse<T>>;
+    };
+    /**
+     * Structured completion that may invoke server-side tools (Anthropic
+     * built-ins like `web_search`) and/or custom client-side tools before
+     * emitting the final structured payload.
+     *
+     * Only implemented by callers that natively support tool-use loops (today:
+     * `AnthropicLlmCaller`). `GatewayLlmCaller` does NOT implement this because
+     * Anthropic's built-in server tools are not exposable through the OpenAI-
+     * compatible Vercel AI Gateway. If a future need warrants it, we can add
+     * a custom-tools-only variant on the gateway (e.g. Tavily passed as a
+     * regular OpenAI-format tool) — see deferred work in `llmCallerAnthropic.ts`.
+     */
+    structuredWithTools?<T extends z.ZodTypeAny>(req: StructuredWithToolsRequest<T>): Promise<StructuredResponse<T>>;
+}
+export interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+    /** Optional inline images for vision-capable models. */
+    imageUrls?: string[];
+}
+export interface ChatRequest {
+    model: ModelChoice;
+    messages: ChatMessage[];
+    temperature?: number;
+    maxTokens?: number;
+    /** Stop sequences. */
+    stop?: string[];
+    /**
+     * Optional fallback model. When primary exhausts retries on a transient/transport
+     * error, the caller will attempt the fallback once (with its own retry budget).
+     * Schema-validation and other non-transient errors do NOT trigger fallback.
+     */
+    fallbackModel?: ModelChoice;
+}
+export interface ChatResponse {
+    text: string;
+    /** Token counts when reported by the provider. */
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+    };
+    /** Provider request id, for tracing/replay. */
+    requestId?: string;
+    /** True if the response came from the fallback model rather than the primary. */
+    usedFallback?: boolean;
+    /** Models attempted, in order (primary first, fallback last). */
+    attemptedModels?: ModelChoice[];
+}
+export interface StructuredRequest<T extends z.ZodTypeAny> {
+    model: ModelChoice;
+    messages: ChatMessage[];
+    schema: T;
+    /** Human-readable schema name shown to the model in the prompt. */
+    schemaName: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** See ChatRequest.fallbackModel. */
+    fallbackModel?: ModelChoice;
+}
+export interface StructuredWithToolsRequest<T extends z.ZodTypeAny> extends StructuredRequest<T> {
+    /**
+     * Server-side tools the LLM provider can execute on the caller's behalf
+     * (e.g. Anthropic's `web_search_20260209`). These do NOT need a local
+     * handler — the provider runs them and injects results back into the
+     * model's context automatically.
+     */
+    serverTools?: Array<{
+        type: "web_search";
+        /** Cap the number of web searches per call to bound cost. */
+        maxUses?: number;
+        /** Optional domain allowlist / blocklist. */
+        allowedDomains?: string[];
+        blockedDomains?: string[];
+    }>;
+    /**
+     * Hard cap on tool-use round-trips before we give up. Defaults to 6 — high
+     * enough for a multi-search planner pass, low enough to bound latency/cost
+     * if the model gets stuck.
+     */
+    maxToolRounds?: number;
+    /**
+     * Apply `cache_control: ephemeral` to the system prompt + tools block so
+     * Anthropic charges ~90% off on cached reads. Right for hot paths where
+     * the same system + tools are re-sent (planner retries, multi-tool
+     * rounds). No-op on non-Anthropic callers.
+     */
+    cachePrompt?: boolean;
+    /**
+     * Enable Anthropic extended thinking. Required for stronger reasoning on
+     * complex planning briefs (T3 premium). `budgetTokens` ≥ 1024 and must be
+     * < maxTokens. Implementations that don't support thinking ignore this
+     * field. When enabled, temperature is forced to 1 (Anthropic requirement).
+     */
+    thinking?: {
+        budgetTokens: number;
+    };
+}
+export interface StructuredResponse<T extends z.ZodTypeAny> {
+    data: z.infer<T>;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+    };
+    requestId?: string;
+    /** True if the response came from the fallback model rather than the primary. */
+    usedFallback?: boolean;
+    /** Models attempted, in order (primary first, fallback last). */
+    attemptedModels?: ModelChoice[];
+}
+/**
+ * Stub LlmCaller for tests and offline development. Throws if anyone calls it
+ * without the host having injected a real implementation.
+ */
+export declare class UnconfiguredLlmCaller implements LlmCaller {
+    chat(): Promise<ChatResponse>;
+    structured<T extends z.ZodTypeAny>(): Promise<StructuredResponse<T>>;
+}
+//# sourceMappingURL=llmCaller.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llmCaller.d.ts","sourceRoot":"","sources":["../../../src/services/agent/llmCaller.ts"],"names":[],"mappings":"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"}

package/lib/services/agent/llmCaller.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnconfiguredLlmCaller = void 0;
+/**
+ * Stub LlmCaller for tests and offline development. Throws if anyone calls it
+ * without the host having injected a real implementation.
+ */
+class UnconfiguredLlmCaller {
+    chat() {
+        throw new Error("LlmCaller not configured. Inject a concrete implementation at host boot.");
+    }
+    structured() {
+        throw new Error("LlmCaller not configured. Inject a concrete implementation at host boot.");
+    }
+}
+exports.UnconfiguredLlmCaller = UnconfiguredLlmCaller;