@agenticmail/enterprise 0.3.2 → 0.4.0

package/src/agent-tools/tools/web-search.ts

@@ -0,0 +1,480 @@
+/**
+ * AgenticMail Agent Tools — Web Search
+ *
+ * Multi-provider web search supporting Brave, Perplexity, and Grok (xAI).
+ */
+
+import type { AnyAgentTool, AgenticMailToolConfig } from '../types.js';
+import { jsonResult, readNumberParam, readStringParam, normalizeSecretInput, wrapWebContent } from '../common.js';
+import {
+  LRUCache,
+  DEFAULT_CACHE_TTL_MINUTES,
+  DEFAULT_TIMEOUT_SECONDS,
+  normalizeCacheKey,
+  readCache,
+  readResponseText,
+  resolveCacheTtlMs,
+  resolveTimeoutSeconds,
+  withTimeout,
+  writeCache,
+} from './web-shared.js';
+
+const SEARCH_PROVIDERS = ['brave', 'perplexity', 'grok'] as const;
+type SearchProvider = (typeof SEARCH_PROVIDERS)[number];
+
+const DEFAULT_SEARCH_COUNT = 5;
+const MAX_SEARCH_COUNT = 10;
+
+const BRAVE_SEARCH_ENDPOINT = 'https://api.search.brave.com/res/v1/web/search';
+const DEFAULT_PERPLEXITY_BASE_URL = 'https://openrouter.ai/api/v1';
+const PERPLEXITY_DIRECT_BASE_URL = 'https://api.perplexity.ai';
+const DEFAULT_PERPLEXITY_MODEL = 'perplexity/sonar-pro';
+const PERPLEXITY_KEY_PREFIXES = ['pplx-'];
+const OPENROUTER_KEY_PREFIXES = ['sk-or-'];
+
+const XAI_API_ENDPOINT = 'https://api.x.ai/v1/responses';
+const DEFAULT_GROK_MODEL = 'grok-4-1-fast';
+
+var SEARCH_CACHE = new LRUCache<Record<string, unknown>>({ maxEntries: 200 });
+var BRAVE_FRESHNESS_SHORTCUTS = new Set(['pd', 'pw', 'pm', 'py']);
+var BRAVE_FRESHNESS_RANGE = /^(\d{4}-\d{2}-\d{2})to(\d{4}-\d{2}-\d{2})$/;
+
+type WebSearchConfig = NonNullable<AgenticMailToolConfig['web']>['search'];
+
+type BraveSearchResult = { title?: string; url?: string; description?: string; age?: string };
+type BraveSearchResponse = { web?: { results?: BraveSearchResult[] } };
+
+type PerplexitySearchResponse = {
+  choices?: Array<{ message?: { content?: string } }>;
+  citations?: string[];
+};
+
+type GrokSearchResponse = {
+  output?: Array<{
+    type?: string;
+    content?: Array<{
+      type?: string;
+      text?: string;
+      annotations?: Array<{ type?: string; url?: string }>;
+    }>;
+  }>;
+  output_text?: string;
+  citations?: string[];
+};
+
+// --- Provider resolution ---
+
+function resolveSearchProvider(search?: WebSearchConfig): SearchProvider {
+  var raw = search?.provider?.trim().toLowerCase() ?? '';
+  if (raw === 'perplexity') return 'perplexity';
+  if (raw === 'grok') return 'grok';
+  return 'brave';
+}
+
+function resolveSearchApiKey(search?: WebSearchConfig): string | undefined {
+  var fromConfig = normalizeSecretInput(search?.apiKey);
+  var fromEnv = normalizeSecretInput(process.env.BRAVE_API_KEY);
+  return fromConfig || fromEnv || undefined;
+}
+
+function resolvePerplexityApiKey(search?: WebSearchConfig): { apiKey?: string; source: string } {
+  var perplexity = search?.perplexity;
+  var fromConfig = normalizeSecretInput(perplexity?.apiKey);
+  if (fromConfig) return { apiKey: fromConfig, source: 'config' };
+  var fromEnvPerplexity = normalizeSecretInput(process.env.PERPLEXITY_API_KEY);
+  if (fromEnvPerplexity) return { apiKey: fromEnvPerplexity, source: 'perplexity_env' };
+  var fromEnvOpenRouter = normalizeSecretInput(process.env.OPENROUTER_API_KEY);
+  if (fromEnvOpenRouter) return { apiKey: fromEnvOpenRouter, source: 'openrouter_env' };
+  return { apiKey: undefined, source: 'none' };
+}
+
+function resolvePerplexityBaseUrl(search?: WebSearchConfig, source = 'none', apiKey?: string): string {
+  var perplexity = search?.perplexity;
+  var fromConfig = perplexity?.baseUrl?.trim() ?? '';
+  if (fromConfig) return fromConfig;
+  if (source === 'perplexity_env') return PERPLEXITY_DIRECT_BASE_URL;
+  if (source === 'openrouter_env') return DEFAULT_PERPLEXITY_BASE_URL;
+  if (source === 'config' && apiKey) {
+    var lower = apiKey.toLowerCase();
+    if (PERPLEXITY_KEY_PREFIXES.some(function(p) { return lower.startsWith(p); })) return PERPLEXITY_DIRECT_BASE_URL;
+    if (OPENROUTER_KEY_PREFIXES.some(function(p) { return lower.startsWith(p); })) return DEFAULT_PERPLEXITY_BASE_URL;
+  }
+  return DEFAULT_PERPLEXITY_BASE_URL;
+}
+
+function resolvePerplexityModel(search?: WebSearchConfig): string {
+  return search?.perplexity?.model?.trim() || DEFAULT_PERPLEXITY_MODEL;
+}
+
+function isDirectPerplexityBaseUrl(baseUrl: string): boolean {
+  try { return new URL(baseUrl.trim()).hostname.toLowerCase() === 'api.perplexity.ai'; }
+  catch { return false; }
+}
+
+function resolvePerplexityRequestModel(baseUrl: string, model: string): string {
+  if (!isDirectPerplexityBaseUrl(baseUrl)) return model;
+  return model.startsWith('perplexity/') ? model.slice('perplexity/'.length) : model;
+}
+
+function resolveGrokApiKey(search?: WebSearchConfig): string | undefined {
+  var grok = search?.grok;
+  var fromConfig = normalizeSecretInput(grok?.apiKey);
+  if (fromConfig) return fromConfig;
+  var fromEnv = normalizeSecretInput(process.env.XAI_API_KEY);
+  return fromEnv || undefined;
+}
+
+function resolveGrokModel(search?: WebSearchConfig): string {
+  return search?.grok?.model?.trim() || DEFAULT_GROK_MODEL;
+}
+
+function resolveGrokInlineCitations(search?: WebSearchConfig): boolean {
+  return search?.grok?.inlineCitations === true;
+}
+
+function resolveSearchCount(value: unknown, fallback: number): number {
+  var parsed = typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+  return Math.max(1, Math.min(MAX_SEARCH_COUNT, Math.floor(parsed)));
+}
+
+// --- Freshness ---
+
+function normalizeFreshness(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  var trimmed = value.trim();
+  if (!trimmed) return undefined;
+  var lower = trimmed.toLowerCase();
+  if (BRAVE_FRESHNESS_SHORTCUTS.has(lower)) return lower;
+  var match = trimmed.match(BRAVE_FRESHNESS_RANGE);
+  if (!match) return undefined;
+  var start = match[1];
+  var end = match[2];
+  if (!isValidIsoDate(start) || !isValidIsoDate(end)) return undefined;
+  if (start > end) return undefined;
+  return start + 'to' + end;
+}
+
+function freshnessToPerplexityRecency(freshness: string | undefined): string | undefined {
+  if (!freshness) return undefined;
+  var map: Record<string, string> = { pd: 'day', pw: 'week', pm: 'month', py: 'year' };
+  return map[freshness] ?? undefined;
+}
+
+function isValidIsoDate(value: string): boolean {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+  var parts = value.split('-').map(function(p) { return Number.parseInt(p, 10); });
+  var date = new Date(Date.UTC(parts[0], parts[1] - 1, parts[2]));
+  return date.getUTCFullYear() === parts[0] && date.getUTCMonth() === parts[1] - 1 && date.getUTCDate() === parts[2];
+}
+
+function resolveSiteName(url: string | undefined): string | undefined {
+  if (!url) return undefined;
+  try { return new URL(url).hostname; }
+  catch { return undefined; }
+}
+
+function extractGrokContent(data: GrokSearchResponse): { text: string | undefined; annotationCitations: string[] } {
+  for (var output of data.output ?? []) {
+    if (output.type !== 'message') continue;
+    for (var block of output.content ?? []) {
+      if (block.type === 'output_text' && typeof block.text === 'string' && block.text) {
+        var urls = (block.annotations ?? [])
+          .filter(function(a) { return a.type === 'url_citation' && typeof a.url === 'string'; })
+          .map(function(a) { return a.url as string; });
+        return { text: block.text, annotationCitations: [...new Set(urls)] };
+      }
+    }
+  }
+  var text = typeof data.output_text === 'string' ? data.output_text : undefined;
+  return { text, annotationCitations: [] };
+}
+
+// --- Provider runners ---
+
+async function runBraveSearch(params: {
+  query: string;
+  count: number;
+  apiKey: string;
+  timeoutSeconds: number;
+  country?: string;
+  search_lang?: string;
+  ui_lang?: string;
+  freshness?: string;
+}): Promise<Record<string, unknown>> {
+  var url = new URL(BRAVE_SEARCH_ENDPOINT);
+  url.searchParams.set('q', params.query);
+  url.searchParams.set('count', String(params.count));
+  if (params.country) url.searchParams.set('country', params.country);
+  if (params.search_lang) url.searchParams.set('search_lang', params.search_lang);
+  if (params.ui_lang) url.searchParams.set('ui_lang', params.ui_lang);
+  if (params.freshness) url.searchParams.set('freshness', params.freshness);
+
+  var res = await fetch(url.toString(), {
+    method: 'GET',
+    headers: { Accept: 'application/json', 'X-Subscription-Token': params.apiKey },
+    signal: withTimeout(undefined, params.timeoutSeconds * 1000),
+  });
+
+  if (!res.ok) {
+    var detailResult = await readResponseText(res, { maxBytes: 64_000 });
+    throw new Error('Brave Search API error (' + res.status + '): ' + (detailResult.text || res.statusText));
+  }
+
+  var data = await res.json() as BraveSearchResponse;
+  var results = Array.isArray(data.web?.results) ? data.web!.results : [];
+  return {
+    query: params.query,
+    provider: 'brave',
+    count: results.length,
+    results: results.map(function(entry) {
+      return {
+        title: entry.title ? wrapWebContent(entry.title, 'web_search') : '',
+        url: entry.url ?? '',
+        description: entry.description ? wrapWebContent(entry.description, 'web_search') : '',
+        published: entry.age || undefined,
+        siteName: resolveSiteName(entry.url) || undefined,
+      };
+    }),
+  };
+}
+
+async function runPerplexitySearch(params: {
+  query: string;
+  apiKey: string;
+  baseUrl: string;
+  model: string;
+  timeoutSeconds: number;
+  freshness?: string;
+}): Promise<Record<string, unknown>> {
+  var baseUrl = params.baseUrl.trim().replace(/\/$/, '');
+  var endpoint = baseUrl + '/chat/completions';
+  var model = resolvePerplexityRequestModel(baseUrl, params.model);
+
+  var body: Record<string, unknown> = {
+    model,
+    messages: [{ role: 'user', content: params.query }],
+  };
+  var recencyFilter = freshnessToPerplexityRecency(params.freshness);
+  if (recencyFilter) body.search_recency_filter = recencyFilter;
+
+  var res = await fetch(endpoint, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: 'Bearer ' + params.apiKey,
+      'HTTP-Referer': 'https://agenticmail.io',
+      'X-Title': 'AgenticMail Web Search',
+    },
+    body: JSON.stringify(body),
+    signal: withTimeout(undefined, params.timeoutSeconds * 1000),
+  });
+
+  if (!res.ok) {
+    var detailResult = await readResponseText(res, { maxBytes: 64_000 });
+    throw new Error('Perplexity API error (' + res.status + '): ' + (detailResult.text || res.statusText));
+  }
+
+  var data = await res.json() as PerplexitySearchResponse;
+  return {
+    query: params.query,
+    provider: 'perplexity',
+    model: params.model,
+    content: wrapWebContent(data.choices?.[0]?.message?.content ?? 'No response'),
+    citations: data.citations ?? [],
+  };
+}
+
+async function runGrokSearch(params: {
+  query: string;
+  apiKey: string;
+  model: string;
+  timeoutSeconds: number;
+  inlineCitations: boolean;
+}): Promise<Record<string, unknown>> {
+  var res = await fetch(XAI_API_ENDPOINT, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: 'Bearer ' + params.apiKey,
+    },
+    body: JSON.stringify({
+      model: params.model,
+      input: [{ role: 'user', content: params.query }],
+      tools: [{ type: 'web_search' }],
+    }),
+    signal: withTimeout(undefined, params.timeoutSeconds * 1000),
+  });
+
+  if (!res.ok) {
+    var detailResult = await readResponseText(res, { maxBytes: 64_000 });
+    throw new Error('xAI API error (' + res.status + '): ' + (detailResult.text || res.statusText));
+  }
+
+  var data = await res.json() as GrokSearchResponse;
+  var extracted = extractGrokContent(data);
+  return {
+    query: params.query,
+    provider: 'grok',
+    model: params.model,
+    content: wrapWebContent(extracted.text ?? 'No response'),
+    citations: (data.citations ?? []).length > 0 ? data.citations! : extracted.annotationCitations,
+  };
+}
+
+// --- Main runner ---
+
+async function runWebSearch(params: {
+  query: string;
+  count: number;
+  apiKey: string;
+  timeoutSeconds: number;
+  cacheTtlMs: number;
+  provider: SearchProvider;
+  country?: string;
+  search_lang?: string;
+  ui_lang?: string;
+  freshness?: string;
+  perplexityBaseUrl?: string;
+  perplexityModel?: string;
+  grokModel?: string;
+  grokInlineCitations?: boolean;
+}): Promise<Record<string, unknown>> {
+  var cacheKey = normalizeCacheKey(params.provider + ':' + params.query + ':' + params.count);
+  var cached = readCache(SEARCH_CACHE, cacheKey);
+  if (cached) return { ...cached.value, cached: true };
+
+  var start = Date.now();
+  var result: Record<string, unknown>;
+
+  if (params.provider === 'perplexity') {
+    result = await runPerplexitySearch({
+      query: params.query,
+      apiKey: params.apiKey,
+      baseUrl: params.perplexityBaseUrl ?? DEFAULT_PERPLEXITY_BASE_URL,
+      model: params.perplexityModel ?? DEFAULT_PERPLEXITY_MODEL,
+      timeoutSeconds: params.timeoutSeconds,
+      freshness: params.freshness,
+    });
+  } else if (params.provider === 'grok') {
+    result = await runGrokSearch({
+      query: params.query,
+      apiKey: params.apiKey,
+      model: params.grokModel ?? DEFAULT_GROK_MODEL,
+      timeoutSeconds: params.timeoutSeconds,
+      inlineCitations: params.grokInlineCitations ?? false,
+    });
+  } else {
+    result = await runBraveSearch({
+      query: params.query,
+      count: params.count,
+      apiKey: params.apiKey,
+      timeoutSeconds: params.timeoutSeconds,
+      country: params.country,
+      search_lang: params.search_lang,
+      ui_lang: params.ui_lang,
+      freshness: params.freshness,
+    });
+  }
+
+  result.tookMs = Date.now() - start;
+  result.externalContent = { untrusted: true, source: 'web_search', provider: params.provider, wrapped: true };
+  writeCache(SEARCH_CACHE, cacheKey, result, params.cacheTtlMs);
+  return result;
+}
+
+// --- Tool creation ---
+
+function missingSearchKeyPayload(provider: SearchProvider) {
+  if (provider === 'perplexity') return {
+    error: 'missing_perplexity_api_key',
+    message: 'web_search (perplexity) needs an API key. Set PERPLEXITY_API_KEY or OPENROUTER_API_KEY, or configure tools.web.search.perplexity.apiKey.',
+  };
+  if (provider === 'grok') return {
+    error: 'missing_xai_api_key',
+    message: 'web_search (grok) needs an xAI API key. Set XAI_API_KEY or configure tools.web.search.grok.apiKey.',
+  };
+  return {
+    error: 'missing_brave_api_key',
+    message: 'web_search needs a Brave Search API key. Set BRAVE_API_KEY or configure tools.web.search.apiKey.',
+  };
+}
+
+export function createWebSearchTool(options?: {
+  config?: AgenticMailToolConfig;
+  sandboxed?: boolean;
+}): AnyAgentTool | null {
+  var search = options?.config?.web?.search;
+  if (search?.enabled === false) return null;
+
+  var provider = resolveSearchProvider(search);
+
+  var description = provider === 'perplexity'
+    ? 'Search the web using Perplexity Sonar. Returns AI-synthesized answers with citations from real-time web search.'
+    : provider === 'grok'
+      ? 'Search the web using xAI Grok. Returns AI-synthesized answers with citations from real-time web search.'
+      : 'Search the web using Brave Search API. Returns titles, URLs, and snippets for fast research.';
+
+  return {
+    label: 'Web Search',
+    name: 'web_search',
+    description,
+    category: 'web',
+    risk: 'low',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search query string.' },
+        count: { type: 'number', description: 'Number of results to return (1-10).', minimum: 1, maximum: MAX_SEARCH_COUNT },
+        country: { type: 'string', description: '2-letter country code for region-specific results.' },
+        search_lang: { type: 'string', description: 'ISO language code for search results.' },
+        ui_lang: { type: 'string', description: 'ISO language code for UI elements.' },
+        freshness: { type: 'string', description: 'Filter by time: pd, pw, pm, py, or YYYY-MM-DDtoYYYY-MM-DD.' },
+      },
+      required: ['query'],
+    },
+    execute: async function(_toolCallId, args) {
+      var params = args as Record<string, unknown>;
+      var perplexityAuth = provider === 'perplexity' ? resolvePerplexityApiKey(search) : undefined;
+      var apiKey = provider === 'perplexity'
+        ? perplexityAuth?.apiKey
+        : provider === 'grok'
+          ? resolveGrokApiKey(search)
+          : resolveSearchApiKey(search);
+
+      if (!apiKey) return jsonResult(missingSearchKeyPayload(provider));
+
+      var query = readStringParam(params, 'query', { required: true });
+      var count = readNumberParam(params, 'count', { integer: true }) ?? search?.maxResults;
+      var country = readStringParam(params, 'country');
+      var search_lang = readStringParam(params, 'search_lang');
+      var ui_lang = readStringParam(params, 'ui_lang');
+      var rawFreshness = readStringParam(params, 'freshness');
+      var freshness = rawFreshness ? normalizeFreshness(rawFreshness) : undefined;
+
+      if (rawFreshness && !freshness) {
+        return jsonResult({
+          error: 'invalid_freshness',
+          message: 'freshness must be one of pd, pw, pm, py, or YYYY-MM-DDtoYYYY-MM-DD.',
+        });
+      }
+
+      var result = await runWebSearch({
+        query,
+        count: resolveSearchCount(count, DEFAULT_SEARCH_COUNT),
+        apiKey,
+        timeoutSeconds: resolveTimeoutSeconds(search?.timeoutSeconds, DEFAULT_TIMEOUT_SECONDS),
+        cacheTtlMs: resolveCacheTtlMs(search?.cacheTtlMinutes, DEFAULT_CACHE_TTL_MINUTES),
+        provider,
+        country,
+        search_lang,
+        ui_lang,
+        freshness,
+        perplexityBaseUrl: resolvePerplexityBaseUrl(search, perplexityAuth?.source, perplexityAuth?.apiKey),
+        perplexityModel: resolvePerplexityModel(search),
+        grokModel: resolveGrokModel(search),
+        grokInlineCitations: resolveGrokInlineCitations(search),
+      });
+      return jsonResult(result);
+    },
+  };
+}

package/src/agent-tools/tools/web-shared.ts

@@ -0,0 +1,232 @@
+/**
+ * AgenticMail Agent Tools — Web Shared Utilities
+ *
+ * LRU caching, timeouts, and response reading utilities for web tools.
+ */
+
+export type CacheEntry<T> = {
+  value: T;
+  expiresAt: number;
+  insertedAt: number;
+};
+
+export const DEFAULT_TIMEOUT_SECONDS = 30;
+export const DEFAULT_CACHE_TTL_MINUTES = 15;
+
+// ─── LRU Cache ─────────────────────────────────────────
+
+export interface LRUCacheOptions {
+  maxEntries?: number;
+  sweepIntervalMs?: number;
+}
+
+var DEFAULT_LRU_MAX_ENTRIES = 200;
+var DEFAULT_SWEEP_INTERVAL_MS = 60_000;
+
+export class LRUCache<T> {
+  private map = new Map<string, CacheEntry<T>>();
+  private readonly maxEntries: number;
+  private sweepTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(opts?: LRUCacheOptions) {
+    this.maxEntries = opts?.maxEntries ?? DEFAULT_LRU_MAX_ENTRIES;
+    var sweepMs = opts?.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
+    if (sweepMs > 0) {
+      this.sweepTimer = setInterval(this.sweep.bind(this), sweepMs);
+      if (this.sweepTimer && typeof this.sweepTimer === 'object' && 'unref' in this.sweepTimer) {
+        (this.sweepTimer as any).unref();
+      }
+    }
+  }
+
+  get(key: string): T | undefined {
+    var entry = this.map.get(key);
+    if (!entry) return undefined;
+    if (Date.now() > entry.expiresAt) {
+      this.map.delete(key);
+      return undefined;
+    }
+    // Move to end (most recently used)
+    this.map.delete(key);
+    this.map.set(key, entry);
+    return entry.value;
+  }
+
+  set(key: string, value: T, ttlMs: number): void {
+    if (ttlMs <= 0) return;
+    // Delete first to reset insertion order
+    this.map.delete(key);
+    // Evict oldest entries if at capacity
+    while (this.map.size >= this.maxEntries) {
+      var oldest = this.map.keys().next();
+      if (!oldest.done) this.map.delete(oldest.value);
+      else break;
+    }
+    this.map.set(key, {
+      value,
+      expiresAt: Date.now() + ttlMs,
+      insertedAt: Date.now(),
+    });
+  }
+
+  has(key: string): boolean {
+    var entry = this.map.get(key);
+    if (!entry) return false;
+    if (Date.now() > entry.expiresAt) {
+      this.map.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  delete(key: string): boolean {
+    return this.map.delete(key);
+  }
+
+  get size(): number {
+    return this.map.size;
+  }
+
+  clear(): void {
+    this.map.clear();
+  }
+
+  sweep(): void {
+    var now = Date.now();
+    for (var [key, entry] of this.map) {
+      if (now > entry.expiresAt) this.map.delete(key);
+    }
+  }
+
+  destroy(): void {
+    if (this.sweepTimer) {
+      clearInterval(this.sweepTimer);
+      this.sweepTimer = null;
+    }
+    this.map.clear();
+  }
+}
+
+// ─── Legacy cache helpers (thin wrappers over LRU) ────
+
+export function resolveTimeoutSeconds(value: unknown, fallback: number): number {
+  var parsed = typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+  return Math.max(1, Math.floor(parsed));
+}
+
+export function resolveCacheTtlMs(value: unknown, fallbackMinutes: number): number {
+  var minutes =
+    typeof value === 'number' && Number.isFinite(value) ? Math.max(0, value) : fallbackMinutes;
+  return Math.round(minutes * 60_000);
+}
+
+export function normalizeCacheKey(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+export function readCache<T>(
+  cache: LRUCache<T>,
+  key: string,
+): { value: T; cached: boolean } | null {
+  var value = cache.get(key);
+  if (value === undefined) return null;
+  return { value, cached: true };
+}
+
+export function writeCache<T>(
+  cache: LRUCache<T>,
+  key: string,
+  value: T,
+  ttlMs: number,
+): void {
+  cache.set(key, value, ttlMs);
+}
+
+// ─── Timeout ──────────────────────────────────────────
+
+export function withTimeout(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal {
+  if (timeoutMs <= 0) return signal ?? new AbortController().signal;
+  var controller = new AbortController();
+  var timer = setTimeout(controller.abort.bind(controller), timeoutMs);
+  if (signal) {
+    signal.addEventListener('abort', function() {
+      clearTimeout(timer);
+      controller.abort();
+    }, { once: true });
+  }
+  controller.signal.addEventListener('abort', function() {
+    clearTimeout(timer);
+  }, { once: true });
+  return controller.signal;
+}
+
+// ─── Response Reading ─────────────────────────────────
+
+export type ReadResponseTextResult = {
+  text: string;
+  truncated: boolean;
+  bytesRead: number;
+};
+
+export async function readResponseText(
+  res: Response,
+  options?: { maxBytes?: number },
+): Promise<ReadResponseTextResult> {
+  var maxBytesRaw = options?.maxBytes;
+  var maxBytes =
+    typeof maxBytesRaw === 'number' && Number.isFinite(maxBytesRaw) && maxBytesRaw > 0
+      ? Math.floor(maxBytesRaw)
+      : undefined;
+
+  var body = (res as unknown as { body?: unknown }).body;
+  if (
+    maxBytes &&
+    body &&
+    typeof body === 'object' &&
+    'getReader' in body &&
+    typeof (body as { getReader: () => unknown }).getReader === 'function'
+  ) {
+    var reader = (body as ReadableStream<Uint8Array>).getReader();
+    var decoder = new TextDecoder();
+    var bytesRead = 0;
+    var truncated = false;
+    var parts: string[] = [];
+
+    try {
+      while (true) {
+        var result = await reader.read();
+        if (result.done) break;
+        if (!result.value || result.value.byteLength === 0) continue;
+
+        var chunk = result.value;
+        if (bytesRead + chunk.byteLength > maxBytes) {
+          var remaining = Math.max(0, maxBytes - bytesRead);
+          if (remaining <= 0) { truncated = true; break; }
+          chunk = chunk.subarray(0, remaining);
+          truncated = true;
+        }
+
+        bytesRead += chunk.byteLength;
+        parts.push(decoder.decode(chunk, { stream: true }));
+
+        if (truncated || bytesRead >= maxBytes) { truncated = true; break; }
+      }
+    } catch {
+      // Best-effort: return whatever we decoded so far.
+    } finally {
+      if (truncated) {
+        try { await reader.cancel(); } catch { /* ignore */ }
+      }
+    }
+
+    parts.push(decoder.decode());
+    return { text: parts.join(''), truncated, bytesRead };
+  }
+
+  try {
+    var text = await res.text();
+    return { text, truncated: false, bytesRead: text.length };
+  } catch {
+    return { text: '', truncated: false, bytesRead: 0 };
+  }
+}