@cat-factory/agents 0.146.6 → 0.147.0

package/dist/providers/resolvers.js

@@ -1,7 +1,8 @@
 import { createAnthropic } from '@ai-sdk/anthropic';
 import { createOpenAI } from '@ai-sdk/openai';
 import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
-import { cloudflareRestBaseUrl } from './endpoints.js';
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { cloudflareRestBaseUrl, DEFAULT_OPENROUTER_ROUTING, isOperatorHostedGateway, OPENROUTER_BASE_URL, } from './endpoints.js';
 // The base, runtime-neutral resolvers. They depend only on `ai` + the `@ai-sdk/*`
 // vendor packages (no Cloudflare bindings, no Node built-ins), so they run on both
 // the Worker and the Node service. Heavier/optional backends (e.g. AWS Bedrock) ship
@@ -42,9 +43,51 @@ export function openAiCompatibleResolver(opts) {
         apiKey: opts.apiKey,
         baseURL: opts.baseURL,
         ...(opts.fetch ? { fetch: opts.fetch } : {}),
+        supportsStructuredOutputs: opts.supportsStructuredOutputs ?? false,
     });
     return (ref) => provider(ref.model);
 }
+/**
+ * Resolver for OpenRouter, which is a GATEWAY rather than one more OpenAI-compatible vendor
+ * and is therefore not served by {@link openAiCompatibleResolver}.
+ *
+ * Three things the generic client structurally cannot do, each of which OpenRouter answers:
+ *
+ *  - **It reports what the call actually cost.** `usage: { include: true }` turns on usage
+ *    accounting, and the reply carries `providerMetadata.openrouter.usage.cost` (real USD, the
+ *    gateway's own ledger) plus `provider` (which upstream served it). Everywhere else this
+ *    platform DERIVES cost from a price table; against a passthrough gateway reselling 300+
+ *    models that derivation is a guess, and this is the one provider that hands over the answer.
+ *  - **It routes per request.** {@link OpenRouterRouting} states the two constraints a
+ *    deployment puts on that routing: keeping the request off an upstream that would silently
+ *    ignore a tool definition, and off one that retains prompts. Both are the deployment's
+ *    rather than constants here, because both can narrow the pool to nothing.
+ *
+ * NOT set here: `structuredOutputs.strict`, which this client already defaults to true ("When
+ * `strict` is left unset, the SDK defaults to `true` for backward compatibility", its own option
+ * doc). The trap runs the OPPOSITE way round from {@link openAiCompatibleResolver}'s, where the
+ * default is false and a schema is silently dropped: here the option exists to opt OUT for a
+ * model whose upstream does not advertise strict mode, so writing `strict: true` would pin the
+ * default while reading like an opt-in nobody may remove.
+ */
+export function openRouterResolver(opts) {
+    const routing = opts.routing ?? DEFAULT_OPENROUTER_ROUTING;
+    const provider = createOpenRouter({
+        apiKey: opts.apiKey,
+        baseURL: opts.baseURL ?? OPENROUTER_BASE_URL,
+        // `strict` is what OpenRouter's own API expects and what this gateway is reached at, as
+        // opposed to a third-party endpoint merely speaking its dialect.
+        compatibility: 'strict',
+        ...(opts.fetch ? { fetch: opts.fetch } : {}),
+    });
+    return (ref) => provider(ref.model, {
+        usage: { include: true },
+        provider: {
+            require_parameters: routing.requireParameters,
+            data_collection: routing.dataCollection,
+        },
+    });
+}
 /**
  * Resolver for Cloudflare-hosted models reached over HTTP (no Workers `AI` binding):
  * either the Workers AI OpenAI-compatible REST endpoint (account id + API token) or an
@@ -56,11 +99,52 @@ export function cloudflareRestResolver(opts) {
     const baseURL = opts.baseURL ?? cloudflareRestBaseUrl(opts);
     return openAiCompatibleResolver({ name: 'cloudflare', apiKey: opts.apiToken, baseURL });
 }
+/**
+ * Turn ONE key-pooled OpenAI-compatible provider into its resolver, dispatching OpenRouter to
+ * {@link openRouterResolver} and everything else to {@link openAiCompatibleResolver}.
+ *
+ * The single place that dispatch is made. Every entry point that builds a direct provider from a
+ * leased key routes through here: the server's `buildDirectResolver`, which is the one this
+ * repo's facades run on, and {@link baseProviderRegistry}, the exported deployment-level seam a
+ * host assembling its own registry uses. Neither may make the OpenRouter-vs-generic decision
+ * itself, because that split is invisible at runtime: the generic client answers correctly, it
+ * just answers with no reported cost and no upstream name, which reads downstream as a gateway
+ * that reports nothing rather than as a mis-wired resolver.
+ *
+ * `supportsStructuredOutputs` is claimed for the CLOUD VENDORS only, and withheld from the
+ * operator-hosted gateways for the same reason a per-user local runner is left on the SDK's own
+ * default: what `bifrost` and `litellm` serve is whatever the operator's `config.yaml` points
+ * them at, routinely an Ollama or vLLM model that answers a `json_schema` request with a 400.
+ * Claiming it there would turn today's silent downgrade to `json_object` into a hard failure on
+ * the first `generateObject` call, and the flag is per PROVIDER, so no caller could exempt them.
+ * The set is DERIVED from the endpoint table's own `null` entries ({@link isOperatorHostedGateway})
+ * rather than re-listed, so a gateway added there cannot be forgotten here.
+ */
+export function directOpenAiCompatibleResolver(provider, apiKey, opts) {
+    if (provider === 'openrouter') {
+        return openRouterResolver({
+            apiKey,
+            baseURL: opts.baseURL,
+            ...(opts.openRouterRouting ? { routing: opts.openRouterRouting } : {}),
+        });
+    }
+    return openAiCompatibleResolver({
+        name: provider,
+        apiKey,
+        baseURL: opts.baseURL,
+        supportsStructuredOutputs: !isOperatorHostedGateway(provider),
+    });
+}
 /**
  * Build the base provider registry from a deployment's credentials. Each provider is
  * registered only when its credential is present, so an unconfigured provider resolves
  * to a clear "Unsupported model provider" error rather than a deep SDK failure. Mix
  * extra registries (e.g. Bedrock, the Workers AI binding) in afterwards.
+ *
+ * The EXPORTED seam, with no caller inside this repo: both facades build their per-scope
+ * providers through the server's `buildDirectResolver` instead. It stays because a host
+ * assembling a registry from raw credentials is the shape this package publishes, and it takes
+ * the same routing option that path does, so the two cannot answer differently.
  */
 export function baseProviderRegistry(opts) {
     const registry = {
@@ -72,13 +156,12 @@ export function baseProviderRegistry(opts) {
             : undefined,
     };
     for (const [provider, upstream] of Object.entries(opts.openAiCompatible ?? {})) {
-        if (upstream?.apiKey) {
-            registry[provider] = openAiCompatibleResolver({
-                name: provider,
-                apiKey: upstream.apiKey,
-                baseURL: upstream.baseURL,
-            });
-        }
+        if (!upstream?.apiKey)
+            continue;
+        registry[provider] = directOpenAiCompatibleResolver(provider, upstream.apiKey, {
+            baseURL: upstream.baseURL,
+            ...(opts.openRouterRouting ? { openRouterRouting: opts.openRouterRouting } : {}),
+        });
     }
     if (opts.cloudflareRest)
         registry['workers-ai'] = cloudflareRestResolver(opts.cloudflareRest);

package/dist/providers/resolvers.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/agents",
-  "version": "0.146.6",
+  "version": "0.147.0",
   "description": "Agent catalog, routing, prompts and fragment library for the Agent Architecture Board.",
   "repository": {
     "type": "git",
@@ -28,16 +28,17 @@
     "@ai-sdk/openai": "^4.0.52",
     "@ai-sdk/openai-compatible": "^3.0.41",
     "@ai-sdk/provider": "^4.0.9",
-    "@cat-factory/contracts": "0.334.0",
-    "@cat-factory/kernel": "0.323.2",
-    "@cat-factory/prompt-fragments": "1.1.17",
+    "@cat-factory/contracts": "0.335.0",
+    "@cat-factory/kernel": "0.324.0",
+    "@cat-factory/prompt-fragments": "1.1.18",
+    "@openrouter/ai-sdk-provider": "^3.0.0",
     "ai": "^7.0.85",
     "handlebars": "^4.7.9",
     "p-map": "^7.0.7",
     "valibot": "^1.4.2"
   },
   "devDependencies": {
-    "@cat-factory/caching": "0.20.55",
+    "@cat-factory/caching": "0.20.56",
     "typescript": "7.0.2",
     "vitest": "^4.1.11"
   },