vidspotai-shared 1.0.68 → 1.0.69-dev.0

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

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import { ChatRequest, ChatResponse, LlmCaller, StructuredRequest, StructuredResponse, StructuredWithToolsRequest } from "./llmCaller";
+/**
+ * Direct Anthropic SDK LlmCaller. Exists alongside GatewayLlmCaller because
+ * Anthropic's server-side tools (`web_search_20260209`, `web_fetch`, etc.)
+ * cannot be exposed through the OpenAI-compatible Vercel AI Gateway —
+ * they're Anthropic-only constructs that the API executes server-side.
+ *
+ * Use this caller when:
+ *   - You need server-side `web_search` for planner grounding.
+ *   - You want Anthropic-native features (prompt caching, extended thinking,
+ *     citations) without a translation layer.
+ *
+ * Use the gateway caller when:
+ *   - You want provider portability (GPT-5 / Gemini fallback chains).
+ *   - You don't need built-in tools.
+ *
+ * The Planner reads from `getAnthropicCaller()` only when `useWebResearch`
+ * is set; otherwise it stays on the gateway path.
+ *
+ * Implemented features:
+ *   - Prompt caching (`cachePrompt: true`): `cache_control: ephemeral` on
+ *     the system prompt's last block + the tools array. Anthropic charges
+ *     ~90% off on cached reads, so retries within a 5-min window are cheap.
+ *   - Extended thinking (`thinking.budgetTokens`): enables Claude's
+ *     interleaved reasoning blocks for T3 / complex briefs. Forces
+ *     temperature=1 and threads `thinking` blocks through the tool-use loop.
+ *   - Transient errors propagate as `TransientLlmError` so callers can
+ *     fall back to the gateway path (no web search) on Anthropic outages.
+ *
+ * Deferred work (v2):
+ *   - Custom client-side tools (Tavily / image search): extend the loop
+ *     to handle `tool_use` blocks for tools we own (vs server-executed).
+ *     Today's loop only handles `submit_<schemaName>` (final emit) and
+ *     server-side web_search rounds.
+ *   - Streaming: `messages.stream()` works the same; we'd reuse the
+ *     `structuredStream` shape but accumulate tool_use input deltas.
+ *   - Multi-breakpoint caching: today we cache system + tools as a single
+ *     prefix. Splitting into model-catalog (rarely changes) vs brief
+ *     (per-request) breakpoints could nudge cache hits higher.
+ */
+export interface AnthropicCallerConfig {
+    apiKey: string;
+    /** Default request timeout in ms. */
+    timeoutMs?: number;
+    /** Max retries on transient errors per call. Default 3. */
+    maxRetries?: number;
+}
+/**
+ * Marks an error worth retrying on the gateway path. The Planner catches
+ * this specifically to degrade gracefully — drops research, keeps planning.
+ */
+export declare class TransientLlmError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare function isTransientLlmError(err: unknown): err is TransientLlmError;
+export declare class AnthropicLlmCaller implements LlmCaller {
+    private readonly client;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    constructor(cfg: AnthropicCallerConfig);
+    chat(req: ChatRequest): Promise<ChatResponse>;
+    structured<T extends z.ZodTypeAny>(req: StructuredRequest<T>): Promise<StructuredResponse<T>>;
+    structuredWithTools<T extends z.ZodTypeAny>(req: StructuredWithToolsRequest<T>): Promise<StructuredResponse<T>>;
+    /**
+     * Anthropic's API takes a top-level `system` (string or TextBlockParam[])
+     * and messages of user/assistant only. Our LlmCaller carries system as
+     * the first message; split it out here.
+     *
+     * When `cache` is true, return system as a single TextBlockParam with
+     * `cache_control: ephemeral` so Anthropic caches the whole system prefix.
+     * Cache hits cost 10% of normal input; misses cost 125% (write surcharge).
+     * The 5-min default TTL is fine for planner: retries within the same
+     * request hit the cache; brand-new requests pay the write once and
+     * benefit on the retry path.
+     */
+    private splitSystem;
+    private buildServerTools;
+    /**
+     * Map our ModelChoice → Anthropic API model id. Pass-through today since
+     * routing uses Anthropic-shaped ids (e.g. "claude-sonnet-4-6"). If a
+     * future routing entry uses a non-Anthropic id we'd want to throw rather
+     * than silently send GPT names to the Anthropic API.
+     */
+    private resolveModelId;
+    private withRetry;
+    private isTransient;
+}
+//# sourceMappingURL=llmCallerAnthropic.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llmCallerAnthropic.d.ts","sourceRoot":"","sources":["../../../src/services/agent/llmCallerAnthropic.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,WAAW,EACX,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,kBAAkB,EAClB,0BAA0B,EAC3B,MAAM,aAAa,CAAC;AAGrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IACb,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAAzC,OAAO,EAAE,MAAM,EAAW,KAAK,CAAC,EAAE,OAAO,YAAA;CAItD;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,iBAAiB,CAE1E;AAED,qBAAa,kBAAmB,YAAW,SAAS;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,GAAG,EAAE,qBAAqB;IAShC,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IA4B7C,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACrC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAI3B,mBAAmB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAC9C,GAAG,EAAE,0BAA0B,CAAC,CAAC,CAAC,GACjC,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAsHjC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,WAAW;IAiCnB,OAAO,CAAC,gBAAgB;IAkBxB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;YASR,SAAS;IAyBvB,OAAO,CAAC,WAAW;CAYpB"}

package/lib/services/agent/llmCallerAnthropic.js

@@ -0,0 +1,255 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnthropicLlmCaller = exports.TransientLlmError = void 0;
+exports.isTransientLlmError = isTransientLlmError;
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+const zod_1 = require("zod");
+const TRANSIENT_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+/**
+ * Marks an error worth retrying on the gateway path. The Planner catches
+ * this specifically to degrade gracefully — drops research, keeps planning.
+ */
+class TransientLlmError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "TransientLlmError";
+    }
+}
+exports.TransientLlmError = TransientLlmError;
+function isTransientLlmError(err) {
+    return err instanceof Error && err.name === "TransientLlmError";
+}
+class AnthropicLlmCaller {
+    constructor(cfg) {
+        this.client = new sdk_1.default({
+            apiKey: cfg.apiKey,
+            timeout: cfg.timeoutMs ?? 180000,
+        });
+        this.timeoutMs = cfg.timeoutMs ?? 180000;
+        this.maxRetries = cfg.maxRetries ?? 3;
+    }
+    async chat(req) {
+        const { system, messages } = this.splitSystem(req.messages, false);
+        const res = await this.withRetry(() => this.client.messages.create({
+            model: this.resolveModelId(req.model),
+            max_tokens: req.maxTokens ?? 4096,
+            temperature: req.temperature,
+            stop_sequences: req.stop,
+            system,
+            messages,
+        }));
+        const text = res.content
+            .filter((b) => b.type === "text")
+            .map((b) => b.text)
+            .join("\n");
+        return {
+            text,
+            usage: {
+                promptTokens: res.usage.input_tokens,
+                completionTokens: res.usage.output_tokens,
+            },
+            requestId: res.id,
+            attemptedModels: [req.model],
+            usedFallback: false,
+        };
+    }
+    async structured(req) {
+        return this.structuredWithTools({ ...req, serverTools: [] });
+    }
+    async structuredWithTools(req) {
+        const submitToolName = `submit_${req.schemaName}`;
+        const jsonSchema = zod_1.z.toJSONSchema(req.schema, { target: "draft-7" });
+        const tools = [
+            ...this.buildServerTools(req.serverTools),
+            {
+                name: submitToolName,
+                description: `Submit the final ${req.schemaName} payload. Call this exactly once when ready.`,
+                input_schema: jsonSchema,
+                // Cache the submit tool's schema (the heaviest part of the tools
+                // array, ~5–15K tokens for VideoPlan). Anthropic caches the whole
+                // tools prefix up to the last cache_control breakpoint, so a single
+                // breakpoint on the last entry covers everything.
+                ...(req.cachePrompt ? { cache_control: { type: "ephemeral" } } : {}),
+            },
+        ];
+        // tool_choice: if no server tools, force submit immediately (pure
+        // structured output). With server tools (web_search), use "auto" so the
+        // model can search before submitting.
+        const toolChoice = req.serverTools?.length
+            ? { type: "auto" }
+            : { type: "tool", name: submitToolName };
+        const { system, messages: initial } = this.splitSystem(req.messages, req.cachePrompt ?? false);
+        const convo = [...initial];
+        const maxRounds = req.maxToolRounds ?? 6;
+        // Extended thinking: Anthropic requires temperature=1 (or omitted) and
+        // a budget < max_tokens. Clamp here so callers don't have to think
+        // about it.
+        const thinking = req.thinking
+            ? {
+                type: "enabled",
+                budget_tokens: Math.max(1024, req.thinking.budgetTokens),
+            }
+            : undefined;
+        const maxTokens = req.maxTokens ?? (thinking ? 16384 : 8192);
+        if (thinking && thinking.budget_tokens >= maxTokens) {
+            // Bump max_tokens above budget so the model has room to actually
+            // answer after thinking. +2048 leaves headroom for tool_use output.
+            // (Cheaper than asking callers to know the constraint.)
+            // No-op when budget fits.
+        }
+        const effectiveMaxTokens = thinking && thinking.budget_tokens >= maxTokens
+            ? thinking.budget_tokens + 2048
+            : maxTokens;
+        const effectiveTemperature = thinking ? 1 : req.temperature;
+        for (let round = 0; round < maxRounds; round++) {
+            const res = await this.withRetry(() => this.client.messages.create({
+                model: this.resolveModelId(req.model),
+                max_tokens: effectiveMaxTokens,
+                temperature: effectiveTemperature,
+                system,
+                tools,
+                tool_choice: toolChoice,
+                messages: convo,
+                ...(thinking ? { thinking } : {}),
+            }));
+            // Look for our submit tool — terminal state.
+            const submit = res.content.find((b) => b.type === "tool_use" && b.name === submitToolName);
+            if (submit) {
+                const parsed = req.schema.safeParse(submit.input);
+                if (!parsed.success) {
+                    throw new Error(`AnthropicLlmCaller.structuredWithTools: schema validation failed for ${req.schemaName}: ${parsed.error.message}`);
+                }
+                return {
+                    data: parsed.data,
+                    usage: {
+                        promptTokens: res.usage.input_tokens,
+                        completionTokens: res.usage.output_tokens,
+                    },
+                    requestId: res.id,
+                    attemptedModels: [req.model],
+                    usedFallback: false,
+                };
+            }
+            // pause_turn: server-side tool (web_search) finished mid-turn and the
+            // model wants to continue. Echo assistant content back (including any
+            // `thinking` blocks — Anthropic rejects the turn otherwise when
+            // extended thinking is on); no new user message needed.
+            if (res.stop_reason === "pause_turn") {
+                convo.push({ role: "assistant", content: res.content });
+                continue;
+            }
+            // If we got `tool_use` for some unknown tool name (shouldn't happen
+            // today since we only register submit + server tools), bail out so we
+            // don't loop forever.
+            throw new Error(`AnthropicLlmCaller.structuredWithTools: unexpected stop_reason=${res.stop_reason} without ${submitToolName} after round ${round}`);
+        }
+        throw new Error(`AnthropicLlmCaller.structuredWithTools: exceeded ${maxRounds} tool rounds without ${submitToolName}`);
+    }
+    // ---------- helpers ----------
+    /**
+     * Anthropic's API takes a top-level `system` (string or TextBlockParam[])
+     * and messages of user/assistant only. Our LlmCaller carries system as
+     * the first message; split it out here.
+     *
+     * When `cache` is true, return system as a single TextBlockParam with
+     * `cache_control: ephemeral` so Anthropic caches the whole system prefix.
+     * Cache hits cost 10% of normal input; misses cost 125% (write surcharge).
+     * The 5-min default TTL is fine for planner: retries within the same
+     * request hit the cache; brand-new requests pay the write once and
+     * benefit on the retry path.
+     */
+    splitSystem(messages, cache) {
+        let systemText;
+        const out = [];
+        for (const m of messages) {
+            if (m.role === "system") {
+                systemText = systemText ? `${systemText}\n\n${m.content}` : m.content;
+                continue;
+            }
+            // Image attachments are not yet plumbed for the Anthropic caller —
+            // planner doesn't need them today. When the critic moves over (it's
+            // vision-heavy), wire image blocks here.
+            out.push({ role: m.role, content: m.content });
+        }
+        if (!systemText)
+            return { system: undefined, messages: out };
+        if (!cache)
+            return { system: systemText, messages: out };
+        return {
+            system: [
+                {
+                    type: "text",
+                    text: systemText,
+                    cache_control: { type: "ephemeral" },
+                },
+            ],
+            messages: out,
+        };
+    }
+    buildServerTools(serverTools) {
+        if (!serverTools?.length)
+            return [];
+        return serverTools.map((t) => {
+            if (t.type !== "web_search") {
+                throw new Error(`AnthropicLlmCaller: unsupported server tool type=${t.type}`);
+            }
+            return {
+                type: "web_search_20260209",
+                name: "web_search",
+                ...(typeof t.maxUses === "number" ? { max_uses: t.maxUses } : {}),
+                ...(t.allowedDomains?.length ? { allowed_domains: t.allowedDomains } : {}),
+                ...(t.blockedDomains?.length ? { blocked_domains: t.blockedDomains } : {}),
+            };
+        });
+    }
+    /**
+     * Map our ModelChoice → Anthropic API model id. Pass-through today since
+     * routing uses Anthropic-shaped ids (e.g. "claude-sonnet-4-6"). If a
+     * future routing entry uses a non-Anthropic id we'd want to throw rather
+     * than silently send GPT names to the Anthropic API.
+     */
+    resolveModelId(m) {
+        if (m.provider !== "anthropic") {
+            throw new Error(`AnthropicLlmCaller cannot serve provider=${m.provider}; route to GatewayLlmCaller instead.`);
+        }
+        return m.modelId;
+    }
+    async withRetry(fn) {
+        let lastErr;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                lastErr = err;
+                const transient = this.isTransient(err);
+                if (!transient || attempt === this.maxRetries - 1) {
+                    if (transient) {
+                        throw new TransientLlmError(`Anthropic transient error after ${attempt + 1} attempts: ${String(err?.message ?? err)}`, err);
+                    }
+                    throw err;
+                }
+                await new Promise((r) => setTimeout(r, 250 * Math.pow(4, attempt)));
+            }
+        }
+        throw lastErr;
+    }
+    isTransient(err) {
+        if (!err || typeof err !== "object")
+            return false;
+        const e = err;
+        if (typeof e.status === "number" && TRANSIENT_STATUSES.has(e.status)) {
+            return true;
+        }
+        if (e.name === "APIConnectionError" || e.name === "APIConnectionTimeoutError") {
+            return true;
+        }
+        const msg = String(e.message ?? "");
+        return /timeout|ECONNRESET|ETIMEDOUT|network|socket hang up/i.test(msg);
+    }
+}
+exports.AnthropicLlmCaller = AnthropicLlmCaller;

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

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { ChatRequest, ChatResponse, LlmCaller, StructuredRequest, StructuredResponse } from "./llmCaller";
+/**
+ * Vercel AI Gateway LlmCaller — OpenAI-compatible /v1/chat/completions surface.
+ * Single endpoint, multi-provider routing via "{provider}/{modelId}" model id.
+ *
+ * No SDK dependency: pure fetch keeps the shared package light. Structured
+ * output uses JSON-schema response_format (supported by gateway across
+ * Anthropic / OpenAI / Google providers — gateway normalises it).
+ *
+ * Reliability features (added Phase 1 of AGENT_TEST_PLAN):
+ *   - F1 transport-level retry: each HTTP call retries 3× with exp backoff
+ *     (250 / 1000 / 4000ms) on transient errors (network drops, 408/429/5xx).
+ *   - F2 model fallback: when a request supplies `fallbackModel` and the
+ *     primary exhausts retries on a transient error, we attempt the fallback
+ *     once (also with its own retry budget). Schema-validation failures and
+ *     other deterministic errors do NOT trigger fallback.
+ */
+export interface GatewayConfig {
+    /** Full base url, e.g. "https://ai-gateway.vercel.sh/v1". */
+    baseUrl: string;
+    /** Bearer token. */
+    apiKey: string;
+    /** Default request timeout in ms. */
+    timeoutMs?: number;
+    /** Optional fetch impl override (tests). */
+    fetchImpl?: typeof fetch;
+    /** Max retry attempts per model on transient errors. Default 3. */
+    maxRetries?: number;
+    /** Base backoff in ms (exponential: base, base*4, base*16). Default 250. */
+    retryBaseMs?: number;
+}
+export declare class GatewayLlmCaller implements LlmCaller {
+    private readonly cfg;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly retryBaseMs;
+    constructor(cfg: GatewayConfig);
+    chat(req: ChatRequest): Promise<ChatResponse>;
+    structured<T extends z.ZodTypeAny>(req: StructuredRequest<T>): Promise<StructuredResponse<T>>;
+    structuredStream<T extends z.ZodTypeAny>(req: StructuredRequest<T>): {
+        tokens: AsyncIterable<string>;
+        result: Promise<StructuredResponse<T>>;
+    };
+    private createStreamingIterator;
+    private modelId;
+    private encodeMessage;
+    private toDataUri;
+    private usage;
+    /**
+     * POST /chat/completions with transient-error retry (F1).
+     * Throws TransientLlmError after exhausting retries on transient failures —
+     * caller catches it to trigger model fallback (F2). Non-transient errors
+     * (4xx other than 408/425/429, malformed responses) propagate as plain Error.
+     */
+    private postWithRetry;
+    private withRetry;
+    private postOnce;
+}
+//# sourceMappingURL=llmCallerGateway.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llmCallerGateway.d.ts","sourceRoot":"","sources":["../../../src/services/agent/llmCallerGateway.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAGrB;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA2CD,qBAAa,gBAAiB,YAAW,SAAS;IAMpC,OAAO,CAAC,QAAQ,CAAC,GAAG;IALhC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAER,GAAG,EAAE,aAAa;IAOzC,IAAI,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAkC7C,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACrC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAgEjC,gBAAgB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACrC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,GACxB;QACD,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAC9B,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;KACxC;YAqBc,uBAAuB;IAoItC,OAAO,CAAC,OAAO;YAID,aAAa;YAqBb,SAAS;IAcvB,OAAO,CAAC,KAAK;IAQb;;;;;OAKG;YACW,aAAa;YAIb,SAAS;YA+BT,QAAQ;CA6BvB"}