@broberg/ai-sdk 0.59.0 → 0.60.0

package/dist/index.d.ts

@@ -52,10 +52,15 @@ interface SearchCache {
     get(key: string): SearchResult | undefined;
     set(key: string, value: SearchResult, ttlMs: number): void;
 }
-/** Running spend per key (tenant + day). Async allowed, so it can live in a database. */
+/** Running spend per key (tenant + day). Async allowed, so it can live in a database.
+ *  `reserve` must CHECK AND ADD in one atomic step (e.g. `UPDATE … SET spent = spent + ?
+ *  WHERE spent + ? <= cap`) and say whether it fitted — a separate read-then-write lets
+ *  parallel calls all pass a cap only one of them fits under. `release` gives a
+ *  reservation back when the call fails. */
 interface SearchCapStore {
+    reserve(key: string, usd: number, capUsd: number): boolean | Promise<boolean>;
+    release(key: string, usd: number): void | Promise<void>;
     getSpent(key: string): number | Promise<number>;
-    addSpent(key: string, usd: number): void | Promise<void>;
 }
 interface SearchOptions {
     /** false = no cache. Default: one in-process memory cache shared by all calls. */
@@ -1877,8 +1882,9 @@ declare const aiConfigSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     labels?: Record<string, string> | undefined;
-    promptCache?: boolean | undefined;
+    costSink?: CostSink | null | undefined;
     byok?: boolean | undefined;
+    promptCache?: boolean | undefined;
     strictPinning?: boolean | undefined;
     defaults?: Partial<Record<"vision" | "video" | "embedding" | "fast" | "smart" | "powerful" | "cheap", {
         provider: string;
@@ -1886,7 +1892,6 @@ declare const aiConfigSchema: z.ZodObject<{
         transport: "http" | "subprocess";
     }>> | undefined;
     providers?: Record<string, ProviderAdapter> | undefined;
-    costSink?: CostSink | null | undefined;
     budget?: {
         perCallUsd?: number | undefined;
         rollingUsd?: number | undefined;
@@ -1897,8 +1902,9 @@ declare const aiConfigSchema: z.ZodObject<{
     } | undefined;
 }, {
     labels?: Record<string, string> | undefined;
-    promptCache?: boolean | undefined;
+    costSink?: CostSink | null | undefined;
     byok?: boolean | undefined;
+    promptCache?: boolean | undefined;
     strictPinning?: boolean | undefined;
     defaults?: Partial<Record<"vision" | "video" | "embedding" | "fast" | "smart" | "powerful" | "cheap", {
         provider: string;
@@ -1906,7 +1912,6 @@ declare const aiConfigSchema: z.ZodObject<{
         transport: "http" | "subprocess";
     }>> | undefined;
     providers?: Record<string, ProviderAdapter> | undefined;
-    costSink?: CostSink | null | undefined;
     budget?: {
         perCallUsd?: number | undefined;
         rollingUsd?: number | undefined;
@@ -2325,8 +2330,8 @@ declare const falStubAdapter: ProviderAdapter;
  *  wires the live adapters. */
 declare const stubProviders: Record<string, ProviderAdapter>;
 
-declare const VERSION: "0.59.0";
-declare const SDK_TAG: "@broberg/ai-sdk@0.59.0";
+declare const VERSION: "0.60.0";
+declare const SDK_TAG: "@broberg/ai-sdk@0.60.0";
 
 /** Built-in defaults. Every entry is overridable via AiConfig.defaults or a
  *  per-call override.
@@ -2853,6 +2858,25 @@ declare function streamTransport(req: StreamTransportRequest): AsyncIterable<str
 
 declare const SEARCH_PRICE_USD: Record<SearchProviderId, number>;
 
+declare const webSearchTool: Tool;
+/** What the app decides — never the model. */
+interface WebSearchContext extends SearchOptions {
+    /** Customer data may be in the query: only Zero-Data-Retention providers. */
+    zdr?: boolean;
+    /** Attribution, e.g. { tenantId } — also selects the tenant's daily cap. */
+    labels?: Record<string, string>;
+}
+interface WebSearchToolResult {
+    provider: string;
+    results: {
+        title: string;
+        url: string;
+        snippet: string;
+    }[];
+}
+/** Run a `web_search` tool call. Throws on invalid arguments before any request. */
+declare function runWebSearch(args: Record<string, unknown>, ctx?: WebSearchContext): Promise<WebSearchToolResult>;
+
 interface SearchRoute {
     /** Readable name — shows up in tests and in the reason a provider was picked. */
     name: string;
@@ -2873,4 +2897,4 @@ declare function memorySearchCache(max?: number): SearchCache;
 
 declare function search(req: SearchRequest, opts?: SearchOptions): Promise<SearchResult>;
 
-export { AZURE_DANISH_VOICES, AZURE_DANISH_VOICE_LIST, type AiClient, type AiConfig, type AzureVoiceInfo, BatchJob, BatchRequestItem, BatchResultItem, type BflAdapterConfig, type BflCredits, BudgetConfig, BudgetExceededError, BudgetGuard, BudgetStore, CONFIG_DERIVED_HOSTS, Capability, type ChatInput, ChatResult, ChatStreamEvent, type CheckVoiceOptions, type ClassifyInput, type ClassifyResult, type Contracts, type CostQuery, CostSink, type CostSummary, type CostSummaryQuery, type CostTimeseriesQuery, DEFAULT_BASE_URLS, DEFAULT_SEARCH_ROUTES, DEFAULT_TIER_MAP, type DesignInput, type DesignResult, type DiscordSinkConfig, ELEVENLABS_DANISH_VOICES, type EmbeddingInput, EmbeddingResult, type ExtractInput, type ExtractResult, type FalAdapterConfig, type FixedHostProvider, type HttpResponse, type ImageInput, ImageResult, type JudgeInput, JudgeResult, LOCALLY_PINNED_HOSTS, type MockupInput, type MockupResult, type ModerationInput, ModerationResult, type OcrInput, OcrResult, type OpenAICompatibleConfig, type PodcastInput, PodcastResult, type PriceDriftResult, type PriceDriftRow, type PricingEntry, ProviderAdapter, type RefreshOptions, type RefreshResult, Region, type RerankInput, type RerankResult, type RouteForecast, SDK_TAG, SEARCH_CACHE_TTL_MS, SEARCH_PRICE_USD, SearchBudgetExceededError, type SearchCache, type SearchCapStore, type SearchCredentials, type SearchItem, SearchKeyMissingError, type SearchOptions, type SearchProviderId, type SearchPurpose, type SearchRequest, type SearchResult, type SearchRoute, type SqliteBudgetStoreConfig, type SqliteSinkConfig, StreamHttpError, type SubprocessResponse, Tier, TierSpec, Tool, ToolCall, type TrainStyleInput, TrainStyleResult, type TranscribeInput, TranscribeResult, type TranslateInput, TranslateResult, Transport, type TransportRequest, type TransportResponse, type TtsInput, type UpmetricsCostClientConfig, UpmetricsCostError, type UpmetricsCostRow, type UpmetricsCostSummary, type UpmetricsCostTimeseries, type UpmetricsSink, type UpmetricsSinkConfig, type UpmetricsSinkStats, Usage, VERSION, type VideoInput, type VisionInput, type VoiceInfo, type VoiceProvider, type VoiceResolveResult, type VoiceStatus, VoiceUnavailableError, ZDR_PROVIDERS, aiConfigSchema, anthropicAdapter, anthropicApiAdapter, anthropicSubprocessAdapter, azureAdapter, bflAdapter, bflCredits, byokAdapter, chatInputSchema, checkPriceDrift, checkVoice, computeCost, createAI, deepinfraAdapter, deeplAdapter, deepseekAdapter, defaultBaseUrl, defaultProviders, discordSink, elevenlabsAdapter, embeddingInputSchema, falAdapter, falStubAdapter, freshUsage, fromProviderToolCall, geminiAdapter, getCostSummary, getPrice, httpTransport, imageInputSchema, isByokKeyed, listAzureDanishVoices, listVoices, makeContracts, makeOpenAICompatibleAdapter, matchLabel, memorySearchCache, messageSchema, mistralAdapter, mistralStubAdapter, multiSink, noopSink, openaiAdapter, openaiStubAdapter, openrouterAdapter, parseClaudeCliJson, parseJsonLoose, refreshAvailability, requestyAdapter, resetRefreshState, resetRegistry, resolveAzureVoice, resolveTier, resolveVoice, routeSearch, search, sqliteBudgetStore, sqliteSink, streamTransport, stubProviders, subprocessTransport, tierSpecSchema, toProviderTools, toolSchema, translateInputSchema, typesafeAdapter, upmetricsCostClient, upmetricsSink, usdFromMicro, vertexAdapter, visionInputSchema, wouldProviderRouteTo, wouldRouteTo };
+export { AZURE_DANISH_VOICES, AZURE_DANISH_VOICE_LIST, type AiClient, type AiConfig, type AzureVoiceInfo, BatchJob, BatchRequestItem, BatchResultItem, type BflAdapterConfig, type BflCredits, BudgetConfig, BudgetExceededError, BudgetGuard, BudgetStore, CONFIG_DERIVED_HOSTS, Capability, type ChatInput, ChatResult, ChatStreamEvent, type CheckVoiceOptions, type ClassifyInput, type ClassifyResult, type Contracts, type CostQuery, CostSink, type CostSummary, type CostSummaryQuery, type CostTimeseriesQuery, DEFAULT_BASE_URLS, DEFAULT_SEARCH_ROUTES, DEFAULT_TIER_MAP, type DesignInput, type DesignResult, type DiscordSinkConfig, ELEVENLABS_DANISH_VOICES, type EmbeddingInput, EmbeddingResult, type ExtractInput, type ExtractResult, type FalAdapterConfig, type FixedHostProvider, type HttpResponse, type ImageInput, ImageResult, type JudgeInput, JudgeResult, LOCALLY_PINNED_HOSTS, type MockupInput, type MockupResult, type ModerationInput, ModerationResult, type OcrInput, OcrResult, type OpenAICompatibleConfig, type PodcastInput, PodcastResult, type PriceDriftResult, type PriceDriftRow, type PricingEntry, ProviderAdapter, type RefreshOptions, type RefreshResult, Region, type RerankInput, type RerankResult, type RouteForecast, SDK_TAG, SEARCH_CACHE_TTL_MS, SEARCH_PRICE_USD, SearchBudgetExceededError, type SearchCache, type SearchCapStore, type SearchCredentials, type SearchItem, SearchKeyMissingError, type SearchOptions, type SearchProviderId, type SearchPurpose, type SearchRequest, type SearchResult, type SearchRoute, type SqliteBudgetStoreConfig, type SqliteSinkConfig, StreamHttpError, type SubprocessResponse, Tier, TierSpec, Tool, ToolCall, type TrainStyleInput, TrainStyleResult, type TranscribeInput, TranscribeResult, type TranslateInput, TranslateResult, Transport, type TransportRequest, type TransportResponse, type TtsInput, type UpmetricsCostClientConfig, UpmetricsCostError, type UpmetricsCostRow, type UpmetricsCostSummary, type UpmetricsCostTimeseries, type UpmetricsSink, type UpmetricsSinkConfig, type UpmetricsSinkStats, Usage, VERSION, type VideoInput, type VisionInput, type VoiceInfo, type VoiceProvider, type VoiceResolveResult, type VoiceStatus, VoiceUnavailableError, type WebSearchContext, type WebSearchToolResult, ZDR_PROVIDERS, aiConfigSchema, anthropicAdapter, anthropicApiAdapter, anthropicSubprocessAdapter, azureAdapter, bflAdapter, bflCredits, byokAdapter, chatInputSchema, checkPriceDrift, checkVoice, computeCost, createAI, deepinfraAdapter, deeplAdapter, deepseekAdapter, defaultBaseUrl, defaultProviders, discordSink, elevenlabsAdapter, embeddingInputSchema, falAdapter, falStubAdapter, freshUsage, fromProviderToolCall, geminiAdapter, getCostSummary, getPrice, httpTransport, imageInputSchema, isByokKeyed, listAzureDanishVoices, listVoices, makeContracts, makeOpenAICompatibleAdapter, matchLabel, memorySearchCache, messageSchema, mistralAdapter, mistralStubAdapter, multiSink, noopSink, openaiAdapter, openaiStubAdapter, openrouterAdapter, parseClaudeCliJson, parseJsonLoose, refreshAvailability, requestyAdapter, resetRefreshState, resetRegistry, resolveAzureVoice, resolveTier, resolveVoice, routeSearch, runWebSearch, search, sqliteBudgetStore, sqliteSink, streamTransport, stubProviders, subprocessTransport, tierSpecSchema, toProviderTools, toolSchema, translateInputSchema, typesafeAdapter, upmetricsCostClient, upmetricsSink, usdFromMicro, vertexAdapter, visionInputSchema, webSearchTool, wouldProviderRouteTo, wouldRouteTo };

package/dist/index.js

@@ -188,13 +188,62 @@ var SearchBudgetExceededError = class extends Error {
   requestedUsd;
 };
 
+// src/search/tool.ts
+var PURPOSES = ["agent", "grounding", "discovery", "monitor"];
+var webSearchTool = {
+  name: "web_search",
+  description: "Search the open web. Returns up to 10 results with title, url and snippet. Set lang to the query's language (e.g. 'da', 'en'). Set fresh when the answer must be recent (news, prices, events).",
+  parameters: {
+    type: "object",
+    properties: {
+      query: { type: "string", minLength: 1, maxLength: 1024, description: "What to search for." },
+      lang: { type: "string", description: "Language of the query, e.g. 'da' or 'en'." },
+      limit: { type: "integer", minimum: 1, maximum: 10, description: "Number of results (default 10)." },
+      purpose: { type: "string", enum: PURPOSES, description: "agent (default), grounding, discovery or monitor." },
+      fresh: { type: "boolean", description: "Results must be recent." }
+    },
+    required: ["query"],
+    additionalProperties: false
+  }
+};
+async function runWebSearch(args, ctx = {}) {
+  const { query, lang, limit, purpose, fresh } = args;
+  if (typeof query !== "string" || query.trim() === "") throw new Error("web_search: `query` must be a non-empty string");
+  if (lang !== void 0 && typeof lang !== "string") throw new Error("web_search: `lang` must be a string");
+  if (limit !== void 0 && (!Number.isInteger(limit) || limit < 1 || limit > 10)) throw new Error("web_search: `limit` must be an integer 1\u201310");
+  if (purpose !== void 0 && !PURPOSES.includes(purpose)) throw new Error(`web_search: \`purpose\` must be one of ${PURPOSES.join(", ")}`);
+  if (fresh !== void 0 && typeof fresh !== "boolean") throw new Error("web_search: `fresh` must be a boolean");
+  const { zdr, labels, ...opts } = ctx;
+  const req = {
+    query,
+    ...lang !== void 0 ? { lang } : {},
+    ...limit !== void 0 ? { limit } : {},
+    ...purpose !== void 0 ? { purpose } : {},
+    ...fresh !== void 0 ? { fresh } : {},
+    ...zdr ? { zdr } : {},
+    ...labels ? { labels } : {}
+  };
+  const r = await search(req, opts);
+  return { provider: r.meta.provider, results: r.items.map((i) => ({ title: i.title, url: i.url, snippet: i.description })) };
+}
+
 // src/search/index.ts
 var sharedCache = memorySearchCache();
 var sharedCapStore = /* @__PURE__ */ (() => {
   const m = /* @__PURE__ */ new Map();
-  return { getSpent: (k) => m.get(k) ?? 0, addSpent: (k, usd) => {
-    m.set(k, (m.get(k) ?? 0) + usd);
-  } };
+  return {
+    // Synchronous, so check-and-add cannot interleave with another call.
+    reserve: (k, usd, cap) => {
+      const s = m.get(k) ?? 0;
+      if (s + usd > cap) return false;
+      m.set(k, s + usd);
+      return true;
+    },
+    release: (k, usd) => {
+      m.set(k, (m.get(k) ?? 0) - usd);
+    },
+    getSpent: (k) => m.get(k) ?? 0
+  };
 })();
 var copenhagenDay = (d) => new Intl.DateTimeFormat("en-CA", { timeZone: "Europe/Copenhagen" }).format(d);
 async function callProvider(provider, req, opts) {
@@ -250,10 +299,10 @@ async function search(req, opts = {}) {
     const key = searchCacheKey(provider, req);
     const hit = cache?.get(key);
     if (hit) return { items: hit.items, meta: { ...hit.meta, cached: true, costUsd: 0, latencyMs: 0 } };
-    if (opts.dailyCapUsd !== void 0) {
-      const spent = await capStore.getSpent(capKey);
-      const price = SEARCH_PRICE_USD[provider];
-      if (spent + price > opts.dailyCapUsd) throw new SearchBudgetExceededError(tenant, day, opts.dailyCapUsd, spent, price);
+    const price = SEARCH_PRICE_USD[provider];
+    const cap = opts.dailyCapUsd ?? Infinity;
+    if (!await capStore.reserve(capKey, price, cap)) {
+      throw new SearchBudgetExceededError(tenant, day, cap, await capStore.getSpent(capKey), price);
     }
     const t0 = performance.now();
     try {
@@ -264,7 +313,6 @@ async function search(req, opts = {}) {
         meta: { provider, latencyMs, cached: false, costUsd: SEARCH_PRICE_USD[provider], ...out.requestId ? { requestId: out.requestId } : {} }
       };
       cache?.set(key, result, ttl);
-      await capStore.addSpent(capKey, result.meta.costUsd);
       try {
         await sink?.record(usageRow(provider, req, result.meta.costUsd, latencyMs));
       } catch {
@@ -272,6 +320,7 @@ async function search(req, opts = {}) {
       return result;
     } catch (e) {
       lastErr = e;
+      await capStore.release(capKey, price);
       if (sink?.recordFailure) {
         try {
           await sink.recordFailure({
@@ -3819,8 +3868,8 @@ var aiConfigSchema = z.object({
 import { randomUUID } from "crypto";
 
 // src/version.ts
-var VERSION = "0.59.0";
-var SDK_TAG = "@broberg/ai-sdk@0.59.0";
+var VERSION = "0.60.0";
+var SDK_TAG = "@broberg/ai-sdk@0.60.0";
 
 // src/cost/sinks/upmetrics.ts
 function isRetryableStatus(status) {
@@ -5437,6 +5486,7 @@ export {
   resolveTier,
   resolveVoice,
   routeSearch,
+  runWebSearch,
   search,
   sqliteBudgetStore,
   sqliteSink,
@@ -5453,6 +5503,7 @@ export {
   usdFromMicro,
   vertexAdapter,
   visionInputSchema,
+  webSearchTool,
   wouldProviderRouteTo,
   wouldRouteTo
 };