@anteros/core 0.0.42 → 0.0.44

package/lib/providers.ts

@@ -1,6 +1,7 @@
 import { AppError } from "./error";
+import { logger } from "../utils/logger";
 import type {
-    AgentCompatible,
+    AgentProtocol,
     AgentMediaPart,
     AgentMessage,
     AgentProvider,
@@ -48,6 +49,12 @@ export type ModelChatRequest = {
     signal?: AbortSignal;
     /** Ask for a JSON object (OpenAI-compatible providers: `response_format`). */
     json?: boolean;
+    /**
+     * Ask for a JSON object **matching this schema** — what the provider can really
+     * enforce: `response_format.json_schema` on OpenAI-compatible gateways, a forced
+     * tool on Anthropic (which has no such field). Takes precedence over `json`.
+     */
+    jsonSchema?: { name: string; description?: string; schema: any };
 };
 
 export type ModelChatResponse = {
@@ -76,18 +83,19 @@ export type ModelStreamEvent =
     | { type: "finish"; finishReason: string };
 
 export type ModelAdapter = {
-    compatible: AgentCompatible;
+    /** The wire protocol this adapter speaks. */
+    protocol: AgentProtocol;
     model: string;
     chat(req: ModelChatRequest): Promise<ModelChatResponse>;
     chatStream(req: ModelChatRequest): AsyncGenerator<ModelStreamEvent, void, unknown>;
 };
 
-const DEFAULT_BASE_URL: Record<AgentCompatible, string> = {
+const DEFAULT_BASE_URL: Record<AgentProtocol, string> = {
     openai: "https://api.openai.com/v1",
     anthropic: "https://api.anthropic.com",
 };
 
-const ENV_API_KEY: Record<AgentCompatible, string[]> = {
+const ENV_API_KEY: Record<AgentProtocol, string[]> = {
     openai: ["ANTEROS_AI_API_KEY", "OPENAI_API_KEY"],
     anthropic: ["ANTEROS_AI_API_KEY", "ANTHROPIC_API_KEY"],
 };
@@ -100,25 +108,33 @@ const EMPTY_USAGE: AgentUsage = { inputTokens: 0, outputTokens: 0, totalTokens:
 
 // ─── Configuration resolution ────────────────────────────────────────────
 
-function resolveCompatible(provider: AgentProvider): AgentCompatible {
-    const compatible = provider.compatible ?? "openai";
-    if (compatible !== "openai" && compatible !== "anthropic") {
-        throw new AppError(`Unknown provider 'compatible': '${compatible}' — expected 'openai' or 'anthropic'`, {
+/**
+ * The wire protocol to speak. `protocol` is canonical; `compatible` is the
+ * deprecated alias kept for definitions written before the rename — `protocol`
+ * wins when both are set, so an override never silently loses to the old field.
+ */
+function resolveProtocol(provider: AgentProvider): AgentProtocol {
+    const protocol = provider.protocol ?? provider.compatible ?? "openai";
+    if (protocol !== "openai" && protocol !== "anthropic") {
+        throw new AppError(`Unknown provider 'protocol': '${protocol}' — expected 'openai' or 'anthropic'`, {
             status: 500,
             code: "AGENT_PROVIDER_INVALID",
         });
     }
-    return compatible;
+    return protocol;
 }
 
-function resolveApiKey(provider: AgentProvider, compatible: AgentCompatible): string {
+/** @deprecated Renamed to `resolveProtocol`. */
+const resolveCompatible = resolveProtocol;
+
+function resolveApiKey(provider: AgentProvider, protocol: AgentProtocol): string {
     if (provider.apiKey) return provider.apiKey;
-    for (const name of ENV_API_KEY[compatible]) {
+    for (const name of ENV_API_KEY[protocol]) {
         const value = Bun.env?.[name] ?? process.env?.[name];
         if (value) return value;
     }
     throw new AppError(
-        `No API key for provider '${provider.model}' (compatible: ${compatible}) — pass \`provider.apiKey\` or set ${ENV_API_KEY[compatible].join(" / ")}`,
+        `No API key for provider '${provider.model}' (protocol: ${protocol}) — pass \`provider.apiKey\` or set ${ENV_API_KEY[protocol].join(" / ")}`,
         { status: 500, code: "AGENT_PROVIDER_NO_API_KEY" },
     );
 }
@@ -128,10 +144,10 @@ function resolveApiKey(provider: AgentProvider, compatible: AgentCompatible): st
  * (`http://localhost:11434` → `http://localhost:11434/v1` for OpenAI-compatible
  * servers), an explicit path is used verbatim.
  */
-function resolveBaseUrl(provider: AgentProvider, compatible: AgentCompatible): string {
-    const raw = provider.baseUrl ?? DEFAULT_BASE_URL[compatible];
+function resolveBaseUrl(provider: AgentProvider, protocol: AgentProtocol): string {
+    const raw = provider.baseUrl ?? DEFAULT_BASE_URL[protocol];
     const trimmed = raw.replace(/\/+$/, "");
-    if (compatible !== "openai") return trimmed;
+    if (protocol !== "openai") return trimmed;
     try {
         const url = new URL(trimmed);
         if (url.pathname === "" || url.pathname === "/") url.pathname = "/v1";
@@ -335,6 +351,14 @@ function thinkingOf(thinking?: AgentThinking): { effort: "low" | "medium" | "hig
     return { effort, budgetTokens };
 }
 
+/** The maximum, forced-tool name an Anthropic run uses for structured output. */
+const SCHEMA_TOOL = "structured_output";
+/**
+ * A gateway that does not know `response_format.json_schema` refuses the request
+ * with a 400 that names it — that is the only case we downgrade for.
+ */
+const SCHEMA_UNSUPPORTED = /response_format|json_schema|json mode/i;
+
 /** `tool_choice` — the one place the two vocabularies differ. */
 function openaiToolChoice(choice?: AgentToolChoice): any | undefined {
     if (!choice || choice === "auto") return undefined;
@@ -372,10 +396,10 @@ function normalizeFinishReason(reason: string | null | undefined): string {
     }
 }
 
-function mapUsage(raw: any, compatible: AgentCompatible): AgentUsage {
+function mapUsage(raw: any, protocol: AgentProtocol): AgentUsage {
     if (!raw) return { ...EMPTY_USAGE };
-    const input = compatible === "anthropic" ? raw.input_tokens : raw.prompt_tokens;
-    const output = compatible === "anthropic" ? raw.output_tokens : raw.completion_tokens;
+    const input = protocol === "anthropic" ? raw.input_tokens : raw.prompt_tokens;
+    const output = protocol === "anthropic" ? raw.output_tokens : raw.completion_tokens;
     const inputTokens = Number(input ?? 0);
     const outputTokens = Number(output ?? 0);
     return {
@@ -407,7 +431,7 @@ async function fetchWithRetry(
     url: string,
     init: RequestInit,
     provider: AgentProvider,
-    compatible: AgentCompatible,
+    protocol: AgentProtocol,
 ): Promise<Response> {
     const options = provider.options ?? {};
     const retries = options.retries ?? DEFAULT_RETRIES;
@@ -425,7 +449,7 @@ async function fetchWithRetry(
                 lastError = new AppError(`Provider error (${response.status}): ${providerErrorMessage(body, response.status)}`, {
                     status: 502,
                     code: "AGENT_PROVIDER_ERROR",
-                    reason: { provider: compatible, status: response.status },
+                    reason: { provider: protocol, status: response.status },
                 });
             } else {
                 return response;
@@ -487,30 +511,30 @@ async function* sseData(body: ReadableStream<Uint8Array>): AsyncGenerator<string
 }
 
 /** An error event sent by the provider in the middle of a stream. */
-function streamError(payload: any, compatible: AgentCompatible): AppError | null {
+function streamError(payload: any, protocol: AgentProtocol): AppError | null {
     const message = payload?.error?.message ?? (typeof payload?.error === "string" ? payload.error : null);
     if (!message) return null;
     return new AppError(`Provider stream error: ${message}`, {
         status: 502,
         code: "AGENT_PROVIDER_ERROR",
-        reason: { provider: compatible },
+        reason: { provider: protocol },
     });
 }
 
 // ─── OpenAI-compatible adapter ───────────────────────────────────────────
 
-function openaiAdapter(provider: AgentProvider, compatible: AgentCompatible): ModelAdapter {
-    const baseUrl = resolveBaseUrl(provider, compatible);
+function openaiAdapter(provider: AgentProvider, protocol: AgentProtocol): ModelAdapter {
+    const baseUrl = resolveBaseUrl(provider, protocol);
     const url = `${baseUrl}/chat/completions`;
     const options = provider.options ?? {};
 
     const headers = (): Record<string, string> => ({
         "Content-Type": "application/json",
-        Authorization: `Bearer ${resolveApiKey(provider, compatible)}`,
+        Authorization: `Bearer ${resolveApiKey(provider, protocol)}`,
         ...(provider.headers ?? {}),
     });
 
-    const body = (req: ModelChatRequest, stream: boolean): any => {
+    const body = (req: ModelChatRequest, stream: boolean, downgrade = false): any => {
         const payload: any = {
             model: provider.model,
             messages: openaiMessages(req.system, req.messages),
@@ -525,7 +549,20 @@ function openaiAdapter(provider: AgentProvider, compatible: AgentCompatible): Mo
         const temperature = req.temperature ?? options.temperature;
         if (temperature !== undefined) payload.temperature = temperature;
         if (options.topP !== undefined) payload.top_p = options.topP;
-        if (req.json) payload.response_format = { type: "json_object" };
+        // `json_schema` is the real constraint (the gateway validates against it);
+        // `json_object` only says "an object" and leaves the shape to the prompt
+        if (req.jsonSchema && !downgrade) {
+            payload.response_format = {
+                type: "json_schema",
+                json_schema: {
+                    name: req.jsonSchema.name,
+                    ...(req.jsonSchema.description ? { description: req.jsonSchema.description } : {}),
+                    schema: req.jsonSchema.schema,
+                },
+            };
+        } else if (req.json) {
+            payload.response_format = { type: "json_object" };
+        }
         if (stream) {
             payload.stream = true;
             payload.stream_options = { include_usage: true };
@@ -533,24 +570,49 @@ function openaiAdapter(provider: AgentProvider, compatible: AgentCompatible): Mo
         return payload;
     };
 
+    /**
+     * POST the request, downgrading a rejected `json_schema` **once**. OpenAI-compatible
+     * gateways are of very uneven quality: one that refuses the field still answers
+     * `json_object`, and the schema is then only enforced by the prompt and the repair
+     * turn — better than failing the run.
+     */
+    const post = async (req: ModelChatRequest, stream: boolean): Promise<Response> => {
+        const send = (downgrade: boolean) => fetchWithRetry(url, {
+            method: "POST",
+            headers: headers(),
+            body: JSON.stringify(body(req, stream, downgrade)),
+            signal: req.signal,
+        }, provider, protocol);
+
+        const response = await send(false);
+        if (response.ok || !req.jsonSchema || response.status !== 400) return response;
+
+        const text = await response.text().catch(() => "");
+        // Not about the schema — hand the error back as it came
+        if (!SCHEMA_UNSUPPORTED.test(text)) {
+            return new Response(text, { status: response.status, headers: { "Content-Type": "application/json" } });
+        }
+
+        logger.file("warn", "agent: provider refused json_schema, retrying with json_object", {
+            model: provider.model,
+            provider: protocol,
+        });
+        return send(true);
+    };
+
     return {
-        compatible,
+        protocol,
         model: provider.model,
 
         async chat(req) {
-            const response = await fetchWithRetry(url, {
-                method: "POST",
-                headers: headers(),
-                body: JSON.stringify(body(req, false)),
-                signal: req.signal,
-            }, provider, compatible);
+            const response = await post(req, false);
 
             if (!response.ok) {
                 const text = await response.text().catch(() => "");
                 throw new AppError(`Provider error (${response.status}): ${providerErrorMessage(text, response.status)}`, {
                     status: 502,
                     code: "AGENT_PROVIDER_ERROR",
-                    reason: { provider: compatible, status: response.status },
+                    reason: { provider: protocol, status: response.status },
                 });
             }
 
@@ -571,25 +633,20 @@ function openaiAdapter(provider: AgentProvider, compatible: AgentCompatible): Mo
                     : {}),
                 toolCalls,
                 finishReason: normalizeFinishReason(choice?.finish_reason),
-                usage: mapUsage(raw?.usage, compatible),
+                usage: mapUsage(raw?.usage, protocol),
                 raw,
             };
         },
 
         async *chatStream(req) {
-            const response = await fetchWithRetry(url, {
-                method: "POST",
-                headers: headers(),
-                body: JSON.stringify(body(req, true)),
-                signal: req.signal,
-            }, provider, compatible);
+            const response = await post(req, true);
 
             if (!response.ok || !response.body) {
                 const text = await response.text().catch(() => "");
                 throw new AppError(`Provider error (${response.status}): ${providerErrorMessage(text, response.status)}`, {
                     status: 502,
                     code: "AGENT_PROVIDER_ERROR",
-                    reason: { provider: compatible, status: response.status },
+                    reason: { provider: protocol, status: response.status },
                 });
             }
 
@@ -601,7 +658,7 @@ function openaiAdapter(provider: AgentProvider, compatible: AgentCompatible): Mo
                 } catch {
                     continue;
                 }
-                const error = streamError(payload, compatible);
+                const error = streamError(payload, protocol);
                 if (error) throw error;
 
                 const choice = payload?.choices?.[0];
@@ -625,7 +682,7 @@ function openaiAdapter(provider: AgentProvider, compatible: AgentCompatible): Mo
                         };
                     }
                 }
-                if (payload?.usage) yield { type: "usage", usage: mapUsage(payload.usage, compatible) };
+                if (payload?.usage) yield { type: "usage", usage: mapUsage(payload.usage, protocol) };
                 if (choice?.finish_reason) yield { type: "finish", finishReason: normalizeFinishReason(choice.finish_reason) };
             }
         },
@@ -634,18 +691,25 @@ function openaiAdapter(provider: AgentProvider, compatible: AgentCompatible): Mo
 
 // ─── Anthropic adapter ───────────────────────────────────────────────────
 
-function anthropicAdapter(provider: AgentProvider, compatible: AgentCompatible): ModelAdapter {
-    const baseUrl = resolveBaseUrl(provider, compatible);
+function anthropicAdapter(provider: AgentProvider, protocol: AgentProtocol): ModelAdapter {
+    const baseUrl = resolveBaseUrl(provider, protocol);
     const url = `${baseUrl}/v1/messages`;
     const options = provider.options ?? {};
 
     const headers = (): Record<string, string> => ({
         "Content-Type": "application/json",
-        "x-api-key": resolveApiKey(provider, compatible),
+        "x-api-key": resolveApiKey(provider, protocol),
         "anthropic-version": "2023-06-01",
         ...(provider.headers ?? {}),
     });
 
+    /**
+     * Does this run ask for a schema, and can Anthropic honour it? A forced tool is
+     * incompatible with extended thinking (the API refuses `tool_choice` then) — the
+     * schema is still asked for in the prompt, and the repair turn still validates.
+     */
+    const wantsSchema = (req: ModelChatRequest): boolean => !!req.jsonSchema && !thinkingOf(req.thinking);
+
     const body = (req: ModelChatRequest, stream: boolean): any => {
         const converted = anthropicMessages(req.messages);
         const system = [req.system, converted.system].filter(Boolean).join("\n\n");
@@ -661,10 +725,27 @@ function anthropicAdapter(provider: AgentProvider, compatible: AgentCompatible):
                 ? thinking.budgetTokens + 1_024
                 : maxTokens,
         };
-        if (system) payload.system = system;
-        if (req.tools?.length) {
-            payload.tools = anthropicToolSpecs(req.tools);
-            const toolChoice = anthropicToolChoice(req.toolChoice);
+        if (system) {
+            // A prompt-cache breakpoint: everything up to here (instructions, skills,
+            // working memory, tools) is billed once instead of on every run
+            payload.system = options.cache
+                ? [{ type: "text", text: system, cache_control: { type: "ephemeral" } }]
+                : system;
+        }
+
+        // The Messages API has no `response_format`: the schema is carried by a tool
+        // the model is **forced** to call, and the adapter turns that call into text
+        const schemaTool = wantsSchema(req)
+            ? [{ name: SCHEMA_TOOL, description: "Return the answer as a JSON object matching the schema.", input_schema: req.jsonSchema!.schema }]
+            : [];
+        const specs = [...(req.tools?.length ? anthropicToolSpecs(req.tools) : []), ...schemaTool];
+        if (specs.length) {
+            payload.tools = options.cache
+                ? [...specs.slice(0, -1), { ...specs[specs.length - 1]!, cache_control: { type: "ephemeral" } }]
+                : specs;
+            const toolChoice = schemaTool.length
+                ? { type: "tool", name: SCHEMA_TOOL }
+                : anthropicToolChoice(req.toolChoice);
             if (toolChoice) payload.tool_choice = toolChoice;
         }
         if (thinking) payload.thinking = { type: "enabled", budget_tokens: thinking.budgetTokens };
@@ -677,7 +758,7 @@ function anthropicAdapter(provider: AgentProvider, compatible: AgentCompatible):
     };
 
     return {
-        compatible,
+        protocol,
         model: provider.model,
 
         async chat(req) {
@@ -686,20 +767,20 @@ function anthropicAdapter(provider: AgentProvider, compatible: AgentCompatible):
                 headers: headers(),
                 body: JSON.stringify(body(req, false)),
                 signal: req.signal,
-            }, provider, compatible);
+            }, provider, protocol);
 
             if (!response.ok) {
                 const text = await response.text().catch(() => "");
                 throw new AppError(`Provider error (${response.status}): ${providerErrorMessage(text, response.status)}`, {
                     status: 502,
                     code: "AGENT_PROVIDER_ERROR",
-                    reason: { provider: compatible, status: response.status },
+                    reason: { provider: protocol, status: response.status },
                 });
             }
 
             const raw: any = await response.json();
             const blocks: any[] = Array.isArray(raw?.content) ? raw.content : [];
-            const toolCalls = blocks
+            const calls = blocks
                 .filter((block) => block?.type === "tool_use")
                 .map((block: any, index: number) => ({
                     id: block?.id ?? `toolu_${index}`,
@@ -707,8 +788,15 @@ function anthropicAdapter(provider: AgentProvider, compatible: AgentCompatible):
                     argsText: JSON.stringify(block?.input ?? {}),
                 }));
 
+            // The forced schema tool **is** the answer: it becomes the text, so the
+            // runtime never sees a tool call it would try to execute
+            const forced = wantsSchema(req) ? calls.find((call) => call.name === SCHEMA_TOOL) : undefined;
+            const toolCalls = forced ? calls.filter((call) => call !== forced) : calls;
+
             return {
-                text: blocks.filter((block) => block?.type === "text").map((block) => block.text).join(""),
+                text: forced
+                    ? forced.argsText
+                    : blocks.filter((block) => block?.type === "text").map((block) => block.text).join(""),
                 toolCalls,
                 // The raw blocks are kept: a tool round must echo the **signed** ones back
                 ...(blocks.some((block) => block?.type === "thinking" || block?.type === "redacted_thinking")
@@ -722,7 +810,7 @@ function anthropicAdapter(provider: AgentProvider, compatible: AgentCompatible):
                     }
                     : {}),
                 finishReason: normalizeFinishReason(raw?.stop_reason),
-                usage: mapUsage(raw?.usage, compatible),
+                usage: mapUsage(raw?.usage, protocol),
                 raw,
             };
         },
@@ -731,20 +819,22 @@ function anthropicAdapter(provider: AgentProvider, compatible: AgentCompatible):
             // Thinking blocks, accumulated by index — signatures included, so the run
             // can echo them back if the model then asks for a tool
             const thinking = new Map<number, any>();
+            // Index of the forced schema tool, whose deltas are the answer itself
+            let schemaBlock: number | null = null;
 
             const response = await fetchWithRetry(url, {
                 method: "POST",
                 headers: headers(),
                 body: JSON.stringify(body(req, true)),
                 signal: req.signal,
-            }, provider, compatible);
+            }, provider, protocol);
 
             if (!response.ok || !response.body) {
                 const text = await response.text().catch(() => "");
                 throw new AppError(`Provider error (${response.status}): ${providerErrorMessage(text, response.status)}`, {
                     status: 502,
                     code: "AGENT_PROVIDER_ERROR",
-                    reason: { provider: compatible, status: response.status },
+                    reason: { provider: protocol, status: response.status },
                 });
             }
 
@@ -755,7 +845,7 @@ function anthropicAdapter(provider: AgentProvider, compatible: AgentCompatible):
                 } catch {
                     continue;
                 }
-                const error = streamError(payload, compatible);
+                const error = streamError(payload, protocol);
                 if (error) throw error;
 
                 switch (payload?.type) {
@@ -770,6 +860,12 @@ function anthropicAdapter(provider: AgentProvider, compatible: AgentCompatible):
                         const block = payload?.content_block;
                         const index = payload?.index ?? 0;
                         if (block?.type === "tool_use") {
+                            // A forced schema call streams its JSON like any tool call — and
+                            // is surfaced as text instead, see `chat()`
+                            if (wantsSchema(req) && block.name === SCHEMA_TOOL) {
+                                schemaBlock = index;
+                                break;
+                            }
                             yield {
                                 type: "tool_call",
                                 index,
@@ -799,6 +895,11 @@ function anthropicAdapter(provider: AgentProvider, compatible: AgentCompatible):
                             block.signature = delta.signature;
                             thinking.set(index, block);
                         } else if (delta?.type === "input_json_delta" && delta.partial_json) {
+                            // The schema tool's JSON is the answer, token by token
+                            if (index === schemaBlock) {
+                                yield { type: "text", text: delta.partial_json };
+                                break;
+                            }
                             yield { type: "tool_call", index, argsText: delta.partial_json };
                         }
                         break;
@@ -816,7 +917,7 @@ function anthropicAdapter(provider: AgentProvider, compatible: AgentCompatible):
                         throw new AppError(`Provider stream error: ${payload?.error?.message ?? "unknown"}`, {
                             status: 502,
                             code: "AGENT_PROVIDER_ERROR",
-                            reason: { provider: compatible },
+                            reason: { provider: protocol },
                         });
                 }
             }
@@ -842,15 +943,17 @@ function resolveProvider(provider: AgentProvider): ModelAdapter {
     if (!provider?.model) {
         throw new AppError("`provider.model` is required", { status: 500, code: "AGENT_PROVIDER_INVALID" });
     }
-    const compatible = resolveCompatible(provider);
-    return compatible === "anthropic"
-        ? anthropicAdapter(provider, compatible)
-        : openaiAdapter(provider, compatible);
+    const protocol = resolveProtocol(provider);
+    return protocol === "anthropic"
+        ? anthropicAdapter(provider, protocol)
+        : openaiAdapter(provider, protocol);
 }
 
 export {
     EMPTY_USAGE,
     DEFAULT_MAX_TOKENS,
+    resolveProtocol,
+    /** @deprecated Renamed to `resolveProtocol`. */
     resolveCompatible,
     resolveApiKey,
     resolveBaseUrl,