@agentguard-run/spend 0.2.2 → 0.4.0

package/src/coach/conversation.ts

@@ -0,0 +1,248 @@
+/**
+ * AgentGuard(TM) Spend: Coach conversation state.
+ *
+ * Patent notice: Protected by U.S. patent-pending technology
+ * (App. Nos. 63/983,615; 63/983,621; 63/983,843; 63/984,626;
+ * 64/071,781; 64/071,789).
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { CapabilityTier, SpendCap, SpendPolicy } from '../types';
+
+export type CoachQuestionId = 'building' | 'scale' | 'tasks' | 'budget' | 'confirm';
+
+export interface CoachQuestion {
+  id: CoachQuestionId;
+  prompt: string;
+}
+
+export interface CoachAnswers {
+  building?: string;
+  scale?: string;
+  tasks?: string;
+  budget?: string;
+  confirm?: string;
+  language?: 'ts' | 'py';
+}
+
+export interface CoachBusinessProfile {
+  vertical: string;
+  tenantId: string;
+  teamSize: number;
+  monthlyVolume: number;
+  tasks: string[];
+  monthlyBudgetCents: number;
+  requiredCapability: CapabilityTier;
+  primaryModel: string;
+  fallbackModel: string;
+  perCallCapCents: number;
+  perDayCapCents: number;
+  perMonthCapCents: number;
+  scopeLabel: string;
+  language: 'ts' | 'py';
+}
+
+export interface ProjectedSavingsRow {
+  label: string;
+  beforeCents: number;
+  afterCents: number;
+  savingsCents: number;
+}
+
+export interface ProjectedSavings {
+  rows: ProjectedSavingsRow[];
+  monthlyBeforeCents: number;
+  monthlyAfterCents: number;
+  monthlySavingsCents: number;
+  savingsPercent: number;
+}
+
+export const COACH_QUESTIONS: CoachQuestion[] = [
+  { id: 'building', prompt: 'What are you building or running? Include your business type and the agent workflow.' },
+  { id: 'scale', prompt: 'How big is the team and roughly how many AI calls, tickets, orders, encounters, matters, or jobs happen per month?' },
+  { id: 'tasks', prompt: 'What are the top 3 AI tasks this agent will perform?' },
+  { id: 'budget', prompt: 'What monthly AI budget or per-task ceiling should this stay under?' },
+  { id: 'confirm', prompt: 'Confirm the setup or list any refinements before I write policy.yaml and quickstart code.' },
+];
+
+const VERTICAL_HINTS: Array<{ vertical: string; needles: string[]; scopeLabel: string; capability: CapabilityTier; primary: string; fallback: string; perCall: number }> = [
+  { vertical: 'law-firm', needles: ['law', 'legal', 'attorney', 'paralegal', 'contract', 'matter', 'discovery'], scopeLabel: 'matter', capability: 'data_write', primary: 'anthropic/claude-sonnet-4-6', fallback: 'anthropic/claude-haiku-4-5', perCall: 300 },
+  { vertical: 'healthcare', needles: ['health', 'medical', 'dental', 'clinic', 'patient', 'chart', 'hipaa', 'encounter'], scopeLabel: 'encounter', capability: 'data_write', primary: 'anthropic.claude-sonnet-4-v1:0', fallback: 'amazon.nova-lite-v1:0', perCall: 300 },
+  { vertical: 'ecommerce', needles: ['shopify', 'commerce', 'store', 'order', 'refund', 'chargeback', 'fraud', 'returns'], scopeLabel: 'order', capability: 'payment_initiate', primary: 'openai/gpt-5-mini', fallback: 'openai/gpt-4o-mini', perCall: 25 },
+  { vertical: 'accounting', needles: ['accounting', 'bookkeeping', 'tax', 'ledger', 'receipt', 'close', 'audit', 'sox'], scopeLabel: 'engagement', capability: 'data_write', primary: 'anthropic/claude-sonnet-4-6', fallback: 'anthropic/claude-haiku-4-5', perCall: 150 },
+  { vertical: 'software', needles: ['software', 'code', 'developer', 'github', 'repo', 'pull request', 'pr'], scopeLabel: 'repo', capability: 'read_only', primary: 'google/gemini-3-flash-preview', fallback: 'openai/gpt-4o-mini', perCall: 10 },
+  { vertical: 'real-estate', needles: ['real estate', 'broker', 'listing', 'mortgage', 'tenant', 'lease', 'property'], scopeLabel: 'transaction', capability: 'data_write', primary: 'openai/gpt-5-mini', fallback: 'openai/gpt-4o-mini', perCall: 50 },
+  { vertical: 'marketing', needles: ['marketing', 'agency', 'content', 'campaign', 'brand'], scopeLabel: 'campaign', capability: 'data_write', primary: 'openai/gpt-5-mini', fallback: 'openai/gpt-4o-mini', perCall: 25 },
+  { vertical: 'local-services', needles: ['salon', 'gym', 'restaurant', 'landscaping', 'construction', 'photography', 'fitness', 'pet'], scopeLabel: 'job', capability: 'data_write', primary: 'openai/gpt-5-mini', fallback: 'openai/gpt-4o-mini', perCall: 25 },
+];
+
+export class CoachConversation {
+  private answers: CoachAnswers = {};
+  private index = 0;
+
+  constructor(initial?: CoachAnswers) {
+    if (initial) this.answers = { ...initial };
+    this.index = firstMissingIndex(this.answers);
+  }
+
+  currentQuestion(): CoachQuestion | null {
+    return COACH_QUESTIONS[this.index] ?? null;
+  }
+
+  answer(value: string): void {
+    const question = this.currentQuestion();
+    if (!question) return;
+    this.answers[question.id] = value.trim();
+  }
+
+  next(): CoachQuestion | null {
+    this.index = Math.min(this.index + 1, COACH_QUESTIONS.length);
+    return this.currentQuestion();
+  }
+
+  back(): CoachQuestion | null {
+    this.index = Math.max(0, this.index - 1);
+    return this.currentQuestion();
+  }
+
+  isComplete(): boolean {
+    return COACH_QUESTIONS.every((question) => Boolean(this.answers[question.id]?.trim()));
+  }
+
+  snapshot(): CoachAnswers {
+    return { ...this.answers };
+  }
+
+  profile(cwd = process.cwd()): CoachBusinessProfile {
+    return buildBusinessProfile(this.answers, cwd);
+  }
+}
+
+export function buildBusinessProfile(answers: CoachAnswers, cwd = process.cwd()): CoachBusinessProfile {
+  const joined = `${answers.building ?? ''} ${answers.scale ?? ''} ${answers.tasks ?? ''}`.toLowerCase();
+  const hint = VERTICAL_HINTS.find((candidate) => candidate.needles.some((needle) => joined.includes(needle))) ?? VERTICAL_HINTS[0]!;
+  const scale = parseScale(answers.scale ?? '');
+  const budgetCents = parseBudgetCents(answers.budget ?? '', Math.max(4900, Math.ceil(scale.monthlyVolume * hint.perCall * 0.35)));
+  const tasks = parseTasks(answers.tasks ?? answers.building ?? hint.vertical);
+  const perMonthCapCents = Math.max(1000, budgetCents);
+  const perDayCapCents = Math.max(hint.perCall * 10, Math.ceil(perMonthCapCents / 20));
+  return {
+    vertical: hint.vertical,
+    tenantId: tenantIdFromBusiness(answers.building ?? hint.vertical),
+    teamSize: scale.teamSize,
+    monthlyVolume: scale.monthlyVolume,
+    tasks,
+    monthlyBudgetCents: perMonthCapCents,
+    requiredCapability: capabilityFor(joined, hint.capability),
+    primaryModel: hint.primary,
+    fallbackModel: hint.fallback,
+    perCallCapCents: hint.perCall,
+    perDayCapCents,
+    perMonthCapCents,
+    scopeLabel: hint.scopeLabel,
+    language: answers.language ?? detectProjectLanguage(cwd),
+  };
+}
+
+export function buildPolicyFromProfile(profile: CoachBusinessProfile): SpendPolicy {
+  const caps: SpendCap[] = [
+    {
+      amountCents: profile.perCallCapCents,
+      window: 'per_call',
+      action: 'downgrade',
+      downgradeTo: profile.fallbackModel,
+      reason: 'Per-call budget reached, route to fallback model',
+    },
+    {
+      amountCents: profile.perDayCapCents,
+      window: 'per_day',
+      action: 'block',
+      reason: 'Daily budget reached',
+    },
+    {
+      amountCents: profile.perMonthCapCents,
+      window: 'per_month',
+      action: 'block',
+      reason: 'Monthly budget reached',
+    },
+  ];
+  return {
+    id: `coach-${profile.vertical}-v1`,
+    name: `Coach generated ${profile.vertical} policy`,
+    scope: { tenantId: profile.tenantId },
+    caps,
+    mode: 'enforce',
+    requiredCapability: profile.requiredCapability,
+    version: 1,
+    effectiveFrom: new Date().toISOString(),
+  };
+}
+
+export function projectedSavings(profile: CoachBusinessProfile): ProjectedSavings {
+  const heavyPerCall = Math.max(profile.perCallCapCents * 4, 100);
+  const routedPerCall = Math.max(1, Math.ceil(profile.perCallCapCents * 0.45));
+  const monthlyBeforeCents = profile.monthlyVolume * heavyPerCall;
+  const monthlyAfterCents = Math.min(profile.perMonthCapCents, profile.monthlyVolume * routedPerCall);
+  const monthlySavingsCents = Math.max(0, monthlyBeforeCents - monthlyAfterCents);
+  return {
+    rows: [
+      { label: 'All traffic on premium model', beforeCents: monthlyBeforeCents, afterCents: 0, savingsCents: 0 },
+      { label: 'Task routed with AgentGuard caps', beforeCents: 0, afterCents: monthlyAfterCents, savingsCents: monthlySavingsCents },
+    ],
+    monthlyBeforeCents,
+    monthlyAfterCents,
+    monthlySavingsCents,
+    savingsPercent: monthlyBeforeCents > 0 ? Math.round((monthlySavingsCents / monthlyBeforeCents) * 100) : 0,
+  };
+}
+
+export function formatCents(cents: number): string {
+  return `$${(cents / 100).toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+export function detectProjectLanguage(cwd: string): 'ts' | 'py' {
+  try {
+    if (fs.existsSync(path.join(cwd, 'pyproject.toml')) || fs.existsSync(path.join(cwd, 'requirements.txt'))) return 'py';
+    if (fs.existsSync(path.join(cwd, 'package.json'))) return 'ts';
+  } catch {
+    return 'ts';
+  }
+  return 'ts';
+}
+
+function firstMissingIndex(answers: CoachAnswers): number {
+  const index = COACH_QUESTIONS.findIndex((question) => !answers[question.id]?.trim());
+  return index === -1 ? COACH_QUESTIONS.length : index;
+}
+
+function parseScale(value: string): { teamSize: number; monthlyVolume: number } {
+  const numbers = (value.match(/\d[\d,]*/g) ?? []).map((part) => Number(part.replace(/,/g, ''))).filter(Number.isFinite);
+  const teamSize = Math.max(1, numbers[0] ?? 3);
+  const monthlyVolume = Math.max(25, numbers[1] ?? numbers[0] ?? 500);
+  return { teamSize, monthlyVolume };
+}
+
+function parseBudgetCents(value: string, fallback: number): number {
+  const money = value.match(/\$?\s*(\d[\d,]*(?:\.\d{1,2})?)/);
+  if (!money) return fallback;
+  const amount = Number(money[1]!.replace(/,/g, ''));
+  if (!Number.isFinite(amount) || amount <= 0) return fallback;
+  return Math.round(amount * 100);
+}
+
+function parseTasks(value: string): string[] {
+  const parts = value.split(/,|\n|;| and /i).map((part) => part.trim()).filter(Boolean);
+  return parts.length > 0 ? parts.slice(0, 3) : ['review requests', 'route models', 'write audit receipts'];
+}
+
+function tenantIdFromBusiness(value: string): string {
+  const cleaned = value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40);
+  return cleaned || 'local-business';
+}
+
+function capabilityFor(text: string, fallback: CapabilityTier): CapabilityTier {
+  if (/refund|payment|charge|dispute|money|invoice/.test(text)) return 'payment_initiate';
+  if (/write|update|ledger|chart|patient|health|phi|sox|legal|contract|tax|student|employment/.test(text)) return 'data_write';
+  return fallback;
+}

package/src/coach/forecast.ts

@@ -0,0 +1,64 @@
+/**
+ * AgentGuard(TM) Spend: local Coach forecast skeleton.
+ *
+ * Reads local decision logs only. No network calls are made.
+ *
+ * Patent notice: Protected by U.S. patent-pending technology
+ * (App. Nos. 63/983,615; 63/983,621; 63/983,843; 63/984,626;
+ * 64/071,781; 64/071,789).
+ */
+
+import type { CoachSpendPoint } from './anomaly';
+
+export interface CoachForecast {
+  daysObserved: number;
+  monthEndCents: number;
+  capCents: number | null;
+  overCap: boolean;
+  message: string;
+}
+
+export function forecastMonthEnd(points: CoachSpendPoint[], capCents: number | null = null, now = new Date()): CoachForecast {
+  const daily = lastThirtyDaily(points, now);
+  if (daily.length === 0) {
+    return { daysObserved: 0, monthEndCents: 0, capCents, overCap: false, message: 'No local spend history found.' };
+  }
+  const slope = linearSlope(daily.map((row, index) => ({ x: index + 1, y: row.cents })));
+  const monthDays = new Date(now.getFullYear(), now.getMonth() + 1, 0).getDate();
+  const elapsed = now.getDate();
+  const observedTotal = daily.reduce((sum, row) => sum + row.cents, 0);
+  const avg = observedTotal / Math.max(1, daily.length);
+  const projectedRemaining = Math.max(0, monthDays - elapsed) * Math.max(0, avg + slope);
+  const monthEndCents = Math.round(observedTotal + projectedRemaining);
+  const overCap = capCents !== null && monthEndCents > capCents;
+  return {
+    daysObserved: daily.length,
+    monthEndCents,
+    capCents,
+    overCap,
+    message: overCap ? 'Projected spend is above cap. Consider a lower fallback model or a tighter per_day cap.' : 'Projected spend is within the current cap.',
+  };
+}
+
+function lastThirtyDaily(points: CoachSpendPoint[], now: Date): Array<{ day: string; cents: number }> {
+  const cutoff = now.getTime() - 30 * 24 * 60 * 60 * 1000;
+  const buckets = new Map<string, number>();
+  for (const point of points) {
+    const t = Date.parse(point.ts);
+    if (!Number.isFinite(t) || t < cutoff) continue;
+    const day = new Date(t).toISOString().slice(0, 10);
+    buckets.set(day, (buckets.get(day) ?? 0) + point.cents);
+  }
+  return [...buckets.entries()].map(([day, cents]) => ({ day, cents })).sort((a, b) => a.day.localeCompare(b.day));
+}
+
+function linearSlope(points: Array<{ x: number; y: number }>): number {
+  if (points.length < 2) return 0;
+  const n = points.length;
+  const sx = points.reduce((sum, point) => sum + point.x, 0);
+  const sy = points.reduce((sum, point) => sum + point.y, 0);
+  const sxx = points.reduce((sum, point) => sum + point.x * point.x, 0);
+  const sxy = points.reduce((sum, point) => sum + point.x * point.y, 0);
+  const denom = n * sxx - sx * sx;
+  return denom === 0 ? 0 : (n * sxy - sx * sy) / denom;
+}

package/src/coach/llm-client.ts

@@ -0,0 +1,247 @@
+/**
+ * AgentGuard(TM) Spend: local Coach LLM client.
+ *
+ * All provider calls go from the customer terminal to the configured provider.
+ * No AgentGuard service is contacted for prompts or completions.
+ *
+ * Patent notice: Protected by U.S. patent-pending technology
+ * (App. Nos. 63/983,615; 63/983,621; 63/983,843; 63/984,626;
+ * 64/071,781; 64/071,789).
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+export type CoachProvider = 'openrouter' | 'openai' | 'anthropic' | 'compatible' | 'mock';
+
+export interface CoachChatMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+export interface CoachClientOptions {
+  provider?: CoachProvider;
+  apiKey?: string;
+  baseUrl?: string;
+  model?: string;
+  timeoutMs?: number;
+  fetchImpl?: FetchLike;
+}
+
+export interface CoachClient {
+  provider: CoachProvider;
+  model: string;
+  baseUrl: string;
+  streamChat(messages: CoachChatMessage[], signal?: AbortSignalLike): AsyncIterable<string>;
+}
+
+type FetchLike = (url: string, init: Record<string, unknown>) => Promise<any>;
+
+type AbortSignalLike = {
+  aborted?: boolean;
+  addEventListener?: (type: 'abort', listener: () => void, options?: { once?: boolean }) => void;
+};
+
+type AbortControllerLike = {
+  signal: AbortSignalLike;
+  abort: () => void;
+};
+
+const DEFAULT_OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
+const DEFAULT_OPENAI_BASE_URL = 'https://api.openai.com/v1';
+const DEFAULT_ANTHROPIC_BASE_URL = 'https://api.anthropic.com/v1';
+const DEFAULT_MODEL = 'openai/gpt-4o-mini';
+
+export function resolveCoachApiKey(provider: CoachProvider = 'openrouter', explicit?: string): string | null {
+  if (explicit?.trim()) return explicit.trim();
+  if (provider === 'openai' && process.env.OPENAI_API_KEY) return process.env.OPENAI_API_KEY;
+  if (provider === 'anthropic' && process.env.ANTHROPIC_API_KEY) return process.env.ANTHROPIC_API_KEY;
+  if ((provider === 'openrouter' || provider === 'compatible') && process.env.OPENROUTER_API_KEY) return process.env.OPENROUTER_API_KEY;
+  if (process.env.AGENTGUARD_COACH_API_KEY) return process.env.AGENTGUARD_COACH_API_KEY;
+  try {
+    const key = fs.readFileSync(path.join(agentguardHome(), 'openrouter-key'), 'utf8').trim();
+    return key.length > 0 ? key : null;
+  } catch {
+    return null;
+  }
+}
+
+export function createCoachClient(options: CoachClientOptions = {}): CoachClient {
+  const provider = options.provider ?? providerFromBaseUrl(options.baseUrl) ?? 'openrouter';
+  const model = options.model ?? (provider === 'anthropic' ? 'claude-sonnet-4-6' : DEFAULT_MODEL);
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultBaseUrl(provider));
+  const fetchImpl = options.fetchImpl ?? globalFetch;
+  const apiKey = resolveCoachApiKey(provider, options.apiKey);
+
+  return {
+    provider,
+    model,
+    baseUrl,
+    async *streamChat(messages: CoachChatMessage[], signal?: AbortSignalLike): AsyncIterable<string> {
+      if (provider === 'mock') {
+        yield 'Mock coach response.';
+        return;
+      }
+      if (!apiKey) throw new Error('No Coach API key configured');
+      if (provider === 'anthropic') {
+        yield* streamAnthropic({ fetchImpl, baseUrl, model, apiKey, messages, signal, timeoutMs: options.timeoutMs });
+      } else {
+        yield* streamOpenAICompatible({ fetchImpl, baseUrl, model, apiKey, messages, signal, timeoutMs: options.timeoutMs });
+      }
+    },
+  };
+}
+
+async function* streamOpenAICompatible(args: {
+  fetchImpl: FetchLike;
+  baseUrl: string;
+  model: string;
+  apiKey: string;
+  messages: CoachChatMessage[];
+  signal?: AbortSignalLike;
+  timeoutMs?: number;
+}): AsyncIterable<string> {
+  const controller = createAbortController();
+  const timer = setTimeout(() => controller.abort(), args.timeoutMs ?? 120_000);
+  const signal = mergeSignal(args.signal, controller.signal);
+  try {
+    const response = await args.fetchImpl(`${args.baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${args.apiKey}`,
+        'content-type': 'application/json',
+        accept: 'text/event-stream',
+      },
+      body: JSON.stringify({ model: args.model, messages: args.messages, stream: true }),
+      signal,
+    });
+    if (!response.ok) throw new Error(`Coach provider HTTP ${response.status}`);
+    yield* parseSseResponse(response, (json) => json?.choices?.[0]?.delta?.content ?? json?.choices?.[0]?.message?.content ?? '');
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function* streamAnthropic(args: {
+  fetchImpl: FetchLike;
+  baseUrl: string;
+  model: string;
+  apiKey: string;
+  messages: CoachChatMessage[];
+  signal?: AbortSignalLike;
+  timeoutMs?: number;
+}): AsyncIterable<string> {
+  const controller = createAbortController();
+  const timer = setTimeout(() => controller.abort(), args.timeoutMs ?? 120_000);
+  const signal = mergeSignal(args.signal, controller.signal);
+  try {
+    const system = args.messages.find((m) => m.role === 'system')?.content ?? '';
+    const messages = args.messages.filter((m) => m.role !== 'system').map((m) => ({ role: m.role === 'assistant' ? 'assistant' : 'user', content: m.content }));
+    const response = await args.fetchImpl(`${args.baseUrl}/messages`, {
+      method: 'POST',
+      headers: {
+        'x-api-key': args.apiKey,
+        'anthropic-version': '2023-06-01',
+        'content-type': 'application/json',
+        accept: 'text/event-stream',
+      },
+      body: JSON.stringify({ model: args.model, system, messages, max_tokens: 1200, stream: true }),
+      signal,
+    });
+    if (!response.ok) throw new Error(`Coach provider HTTP ${response.status}`);
+    yield* parseSseResponse(response, (json) => json?.delta?.text ?? json?.content_block?.text ?? '');
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function* parseSseResponse(response: any, pickText: (json: any) => string): AsyncIterable<string> {
+  let buffer = '';
+  for await (const chunk of responseBodyIterable(response)) {
+    buffer += chunk;
+    const parts = buffer.split('\n\n');
+    buffer = parts.pop() ?? '';
+    for (const part of parts) {
+      const dataLines = part.split('\n').filter((line) => line.startsWith('data:')).map((line) => line.slice(5).trim());
+      for (const data of dataLines) {
+        if (!data || data === '[DONE]') continue;
+        try {
+          const token = pickText(JSON.parse(data));
+          if (token) yield token;
+        } catch {
+          continue;
+        }
+      }
+    }
+  }
+}
+
+async function* responseBodyIterable(response: any): AsyncIterable<string> {
+  const body = response.body;
+  if (!body) return;
+  if (typeof body[Symbol.asyncIterator] === 'function') {
+    for await (const chunk of body) yield chunkToString(chunk);
+    return;
+  }
+  if (typeof body.getReader === 'function') {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      yield decoder.decode(value, { stream: true });
+    }
+  }
+}
+
+function chunkToString(chunk: unknown): string {
+  if (typeof chunk === 'string') return chunk;
+  if (chunk instanceof Uint8Array) return Buffer.from(chunk).toString('utf8');
+  return String(chunk ?? '');
+}
+
+function defaultBaseUrl(provider: CoachProvider): string {
+  if (provider === 'openai') return DEFAULT_OPENAI_BASE_URL;
+  if (provider === 'anthropic') return DEFAULT_ANTHROPIC_BASE_URL;
+  return DEFAULT_OPENROUTER_BASE_URL;
+}
+
+function normalizeBaseUrl(value: string): string {
+  return value.replace(/\/+$/, '');
+}
+
+function providerFromBaseUrl(baseUrl?: string): CoachProvider | null {
+  if (!baseUrl) return null;
+  if (baseUrl.includes('anthropic.com')) return 'anthropic';
+  if (baseUrl.includes('openai.com')) return 'openai';
+  if (baseUrl.includes('openrouter.ai')) return 'openrouter';
+  return 'compatible';
+}
+
+function agentguardHome(): string {
+  return process.env.AGENTGUARD_HOME || path.join(os.homedir(), '.agentguard');
+}
+
+function globalFetch(url: string, init: Record<string, unknown>): Promise<any> {
+  const fetchImpl = (globalThis as { fetch?: FetchLike }).fetch;
+  if (typeof fetchImpl !== 'function') throw new Error('Global fetch is not available. Use Node 20 or newer.');
+  return fetchImpl(url, init);
+}
+
+function createAbortController(): AbortControllerLike {
+  const Controller = (globalThis as { AbortController?: new () => AbortControllerLike }).AbortController;
+  if (Controller) return new Controller();
+  const signal: AbortSignalLike = { aborted: false, addEventListener: () => undefined };
+  return { signal, abort: () => { signal.aborted = true; } };
+}
+
+function mergeSignal(a: AbortSignalLike | undefined, b: AbortSignalLike): AbortSignalLike {
+  if (!a) return b;
+  if (a.aborted) return a;
+  const controller = createAbortController();
+  const abort = () => controller.abort();
+  a.addEventListener?.('abort', abort, { once: true });
+  b.addEventListener?.('abort', abort, { once: true });
+  return controller.signal;
+}