@srouterhq/server 0.0.0-stage → 0.9.0

package/dist/lib/tool-capability.js

@@ -0,0 +1,70 @@
+// Observed tool-calling rejections (#1230).
+//
+// `models.supports_tools` is a declaration, and for custom endpoints it defaults
+// to 1 (migration 20260706_000002): a relay model that actually rejects every
+// request carrying `tools` with a 400 stays a first-class candidate for tool
+// requests, because the only memory of the rejection is the 90s transient
+// cooldown. Auto mode then walks the same dead chain on every tool request
+// until the operator disables the models by hand.
+//
+// This module remembers those rejections in memory and lets the router DEFER
+// such a model for tool-carrying requests only. It is a soft preference, never
+// a filter: a deferred model is still tried once everything else is exhausted,
+// plain chat requests are untouched, and nothing is written to the DB (the
+// `supports_tools` toggle stays the operator's). A client that sends a broken
+// tool schema gets a 400 from every model alike, which defers them all equally
+// and so changes nothing about their order.
+//
+// Keyed per model and per endpoint (`modelStatsKey`), not per key: tool support
+// is a property of the model behind one relay, and sibling keys share it.
+import { modelStatsKey } from './endpoint-scope.js';
+// Distinct REQUESTS (not hops) that must see the rejection before the model is
+// deferred: one odd request must not condemn a model.
+export const TOOL_REJECTION_LIMIT = 3;
+export const TOOL_REJECTION_WINDOW_MS = 60 * 60 * 1000;
+// Long enough to stop the per-request re-walk, short enough that a relay which
+// fixes its tool support comes back the same day without a restart.
+export const TOOL_BENCH_MS = 6 * 60 * 60 * 1000;
+const rejections = new Map(); // statsKey -> rejection timestamps
+const benchedUntil = new Map(); // statsKey -> expiry (ms)
+export function toolCapabilityKey(platform, modelId, endpointScope) {
+    return modelStatsKey(platform, modelId, endpointScope);
+}
+/** Defer this model for tool requests right now (evidence is already conclusive). */
+export function benchForTools(key, now = Date.now()) {
+    const already = (benchedUntil.get(key) ?? 0) > now;
+    benchedUntil.set(key, now + TOOL_BENCH_MS);
+    rejections.delete(key);
+    if (!already) {
+        console.warn(`[ToolCapability] ${key} keeps rejecting tool-calling requests; trying it last for tool requests for ${Math.round(TOOL_BENCH_MS / 3_600_000)}h`);
+    }
+}
+/** One tool-carrying request was rejected as a bad request by this model. */
+export function noteToolRejection(key, now = Date.now()) {
+    const recent = (rejections.get(key) ?? []).filter(t => now - t < TOOL_REJECTION_WINDOW_MS);
+    recent.push(now);
+    if (recent.length >= TOOL_REJECTION_LIMIT)
+        benchForTools(key, now);
+    else
+        rejections.set(key, recent);
+}
+/** The model just served a tool-carrying request: it supports tools after all. */
+export function clearToolRejections(key) {
+    rejections.delete(key);
+    benchedUntil.delete(key);
+}
+export function isToolBenched(platform, modelId, endpointScope, now = Date.now()) {
+    const key = toolCapabilityKey(platform, modelId, endpointScope);
+    const until = benchedUntil.get(key);
+    if (until === undefined)
+        return false;
+    if (until > now)
+        return true;
+    benchedUntil.delete(key);
+    return false;
+}
+export function resetToolCapability() {
+    rejections.clear();
+    benchedUntil.clear();
+}
+//# sourceMappingURL=tool-capability.js.map

package/dist/lib/tool-capability.js.map

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

package/dist/lib/tool-validate.d.ts

@@ -0,0 +1,44 @@
+export declare const TOOL_ARGUMENT_VALIDATION_SETTING = "validate_tool_arguments";
+export declare function isToolArgumentValidationEnabled(): boolean;
+/**
+ * Order-independent serialisation, so two schemas that differ only in key order
+ * share one compiled validator.
+ */
+export declare function stableStringify(value: unknown): string;
+export type ToolArgumentVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Check `argsJson` against `schema`.
+ *
+ * Fails **open** in every case where we cannot form an opinion: no schema, a
+ * schema Ajv will not compile, or arguments that are not JSON at all (the last
+ * is someone else's error to report, and tool-args deliberately passes
+ * unparseable arguments through untouched). Only a definite schema violation
+ * returns a verdict, because the consequence of a verdict is a failover hop.
+ */
+export declare function validateToolArguments(toolName: string, argsJson: string, schema: unknown): ToolArgumentVerdict;
+/**
+ * The error thrown when a tool call cannot be served. The message carries the
+ * marker `invalid tool arguments`, which `isRetryableError` recognises, so the
+ * loop fails over exactly as it does for a dead dialect turn.
+ *
+ * `skipBench` because the PROVIDER is healthy — the model misbehaved, so no
+ * cooldown or score penalty. `skipModelForRequest` because a sibling key would
+ * misbehave identically, so the whole model is ruled out for this request.
+ */
+export declare function invalidToolArgumentsError(displayName: string, reasons: string[]): Error;
+/**
+ * Verdicts for a whole turn's tool calls. Returns the reasons for those that
+ * violate their schema; an empty array means the turn is servable.
+ */
+export declare function invalidToolCallReasons(calls: Array<{
+    function?: {
+        name?: string;
+        arguments?: string;
+    };
+}> | undefined, schemas: Map<string, unknown>): string[];
+//# sourceMappingURL=tool-validate.d.ts.map

package/dist/lib/tool-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-validate.d.ts","sourceRoot":"","sources":["../../src/lib/tool-validate.ts"],"names":[],"mappings":"AAkCA,eAAO,MAAM,gCAAgC,4BAA4B,CAAC;AAE1E,wBAAgB,+BAA+B,IAAI,OAAO,CAazD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQtD;AAoCD,MAAM,MAAM,mBAAmB,GAC3B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,GACd,mBAAmB,CAuBrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,CAMvF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,KAAK,CAAC;IAAE,QAAQ,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC,GAAG,SAAS,EAC9E,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,MAAM,EAAE,CAaV"}

package/dist/lib/tool-validate.js

@@ -0,0 +1,165 @@
+import Ajv2020 from 'ajv/dist/2020.js';
+import { getSetting } from '../db/index.js';
+// A verdict on whether a tool call's arguments actually satisfy the schema the
+// caller declared for that tool.
+//
+// lib/tool-args.ts repairs what it can prove is repairable, and deliberately
+// invents nothing. What it cannot do is say "this is still wrong" — so a call
+// that violates its schema flows on unchallenged, and the Anthropic surface
+// turns it into `input: {}` (routes/anthropic.ts parseToolInput does
+// `try { JSON.parse } catch { return {} }`). The client then gets a tool_use
+// block with no arguments and no explanation, which reads to an agent as the
+// model having chosen to call the tool with nothing.
+//
+// Free-tier models are exactly the population that emits malformed tool calls,
+// and a different model usually gets it right, so the useful response is the
+// one the loop already has for a dead turn: throw before anything is committed
+// and let failover try the next candidate.
+//
+// OFF by default. A false positive here costs a failover hop, and schemas in
+// the wild are strange enough that the honest default is to look before
+// leaping — enable it, watch the trail, then decide.
+/** 2020-12, because that is what zod-to-json-schema and Pydantic v2 emit; a
+ *  draft-07-only Ajv throws on their `$schema`. `strict: false` keeps an
+ *  unknown keyword from being fatal — plenty of real schemas carry vendor
+ *  extensions, and rejecting the schema would fail calls that are fine. */
+const ajv = new Ajv2020({
+    strict: false,
+    allErrors: true,
+    validateFormats: false,
+});
+export const TOOL_ARGUMENT_VALIDATION_SETTING = 'validate_tool_arguments';
+export function isToolArgumentValidationEnabled() {
+    let stored;
+    try {
+        stored = getSetting(TOOL_ARGUMENT_VALIDATION_SETTING);
+    }
+    catch {
+        stored = undefined; // DB not ready — never throw on the proxy hot path.
+    }
+    for (const raw of [stored, process.env.VALIDATE_TOOL_ARGUMENTS]) {
+        if (raw === undefined || raw.trim() === '')
+            continue;
+        const value = raw.trim().toLowerCase();
+        return value === '1' || value === 'true';
+    }
+    return false;
+}
+/**
+ * Order-independent serialisation, so two schemas that differ only in key order
+ * share one compiled validator.
+ */
+export function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+    return `{${entries.join(',')}}`;
+}
+/** Compiled validators, keyed by the schema's stable form. `null` is cached
+ *  too: a schema Ajv refuses to compile must not be recompiled per request. */
+const compiled = new Map();
+/** The stable string is the expensive half, and tool schemas are the same
+ *  object for every call in a request, so memoise per object identity. */
+const stableKeys = new WeakMap();
+function keyFor(schema) {
+    const cached = stableKeys.get(schema);
+    if (cached !== undefined)
+        return cached;
+    const key = stableStringify(schema);
+    stableKeys.set(schema, key);
+    return key;
+}
+function compiledFor(schema) {
+    const key = keyFor(schema);
+    const hit = compiled.get(key);
+    if (hit !== undefined)
+        return hit;
+    let fn = null;
+    try {
+        // Drop `$schema`: a declared dialect Ajv does not recognise is fatal at
+        // compile time, and the dialect is not what we are checking.
+        const { $schema, ...rest } = schema;
+        void $schema;
+        fn = ajv.compile(rest);
+    }
+    catch {
+        fn = null; // Unusable schema — see validateToolArguments, which fails OPEN.
+    }
+    compiled.set(key, fn);
+    return fn;
+}
+/**
+ * Check `argsJson` against `schema`.
+ *
+ * Fails **open** in every case where we cannot form an opinion: no schema, a
+ * schema Ajv will not compile, or arguments that are not JSON at all (the last
+ * is someone else's error to report, and tool-args deliberately passes
+ * unparseable arguments through untouched). Only a definite schema violation
+ * returns a verdict, because the consequence of a verdict is a failover hop.
+ */
+export function validateToolArguments(toolName, argsJson, schema) {
+    if (!schema || typeof schema !== 'object')
+        return { ok: true };
+    const validate = compiledFor(schema);
+    if (!validate)
+        return { ok: true };
+    let parsed;
+    try {
+        parsed = JSON.parse(argsJson);
+    }
+    catch {
+        return { ok: true };
+    }
+    // A tool call's arguments are an object by definition; anything else is a
+    // shape problem the schema will report on its own terms if it cares.
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return { ok: true };
+    if (validate(parsed))
+        return { ok: true };
+    const detail = (validate.errors ?? [])
+        .slice(0, 3)
+        .map(e => `${e.instancePath || '/'} ${e.message ?? 'is invalid'}`)
+        .join('; ');
+    return { ok: false, reason: `${toolName}: ${detail || 'does not match its schema'}` };
+}
+/**
+ * The error thrown when a tool call cannot be served. The message carries the
+ * marker `invalid tool arguments`, which `isRetryableError` recognises, so the
+ * loop fails over exactly as it does for a dead dialect turn.
+ *
+ * `skipBench` because the PROVIDER is healthy — the model misbehaved, so no
+ * cooldown or score penalty. `skipModelForRequest` because a sibling key would
+ * misbehave identically, so the whole model is ruled out for this request.
+ */
+export function invalidToolArgumentsError(displayName, reasons) {
+    const detail = reasons.slice(0, 3).join('; ');
+    return Object.assign(new Error(`invalid tool arguments from ${displayName} (${detail})`), { skipBench: true, skipModelForRequest: true });
+}
+/**
+ * Verdicts for a whole turn's tool calls. Returns the reasons for those that
+ * violate their schema; an empty array means the turn is servable.
+ */
+export function invalidToolCallReasons(calls, schemas) {
+    if (!calls || calls.length === 0)
+        return [];
+    const reasons = [];
+    for (const call of calls) {
+        const name = call.function?.name;
+        const args = call.function?.arguments;
+        if (!name || typeof args !== 'string')
+            continue;
+        const schema = schemas.get(name);
+        if (schema === undefined)
+            continue; // Tool the caller never declared a schema for.
+        const verdict = validateToolArguments(name, args, schema);
+        if (!verdict.ok)
+            reasons.push(verdict.reason);
+    }
+    return reasons;
+}
+//# sourceMappingURL=tool-validate.js.map

package/dist/lib/tool-validate.js.map

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

package/dist/lib/ttfb-budget.d.ts

@@ -0,0 +1,13 @@
+export interface EndpointTtfbStats {
+    p50Ms: number;
+    p95Ms: number;
+    sampleCount: number;
+    weightedSamples: number;
+}
+/** Clear the derived cache; the request log remains the source of truth. */
+export declare function invalidateTtfbBudgetCache(): void;
+/** Decay-weighted nearest-rank percentiles of successful endpoint TTFB. */
+export declare function getEndpointTtfbStats(platform: string, endpointScope?: string, now?: number): EndpointTtfbStats | null;
+/** Give historically slow endpoints their P95 TTFB plus a safety buffer. */
+export declare function getEndpointTimeBudgetMs(baseBudgetMs: number, platform: string, endpointScope?: string, now?: number): number;
+//# sourceMappingURL=ttfb-budget.d.ts.map

package/dist/lib/ttfb-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ttfb-budget.d.ts","sourceRoot":"","sources":["../../src/lib/ttfb-budget.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAsBD,4EAA4E;AAC5E,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AA4FD,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,aAAa,SAAK,EAClB,GAAG,SAAa,GACf,iBAAiB,GAAG,IAAI,CAU1B;AAED,4EAA4E;AAC5E,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,aAAa,SAAK,EAClB,GAAG,SAAa,GACf,MAAM,CAiBR"}

package/dist/lib/ttfb-budget.js

@@ -0,0 +1,153 @@
+import { getDb } from '../db/index.js';
+import { endpointScopeForBaseUrl } from './endpoint-scope.js';
+const DEFAULT_BUFFER_MS = 10_000;
+const DEFAULT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const DEFAULT_HALF_LIFE_MS = 2 * 24 * 60 * 60 * 1000;
+const CACHE_TTL_MS = 60_000;
+// One lucky 90s success must not triple an endpoint's patience: below this
+// many in-window successes the history is an anecdote, not a distribution.
+const DEFAULT_MIN_SAMPLES = 5;
+// Logged TTFB runs from request start, so it includes the hops that failed
+// before the endpoint was reached. A widened budget admits later successes,
+// which log a larger TTFB, which widens the budget again — without a ceiling
+// the allowance ratchets up by one buffer per refresh. Cap it at a multiple of
+// the operator's base budget, which stays the declared unit of patience.
+const MAX_BUDGET_MULTIPLIER = 3;
+// The buffer is absolute, so against a small operator budget (say 6s) it would
+// hand a 200ms endpoint 10s of patience. Only an endpoint whose P95 is itself a
+// large share of the base counts as slow; with the 45s default this changes
+// nothing, because a P95 under 22.5s plus the buffer already fits the base.
+const SLOW_P95_BASE_FRACTION = 0.5;
+let cache;
+/** Clear the derived cache; the request log remains the source of truth. */
+export function invalidateTtfbBudgetCache() {
+    cache = undefined;
+}
+function readConfig(db) {
+    const rows = db.prepare(`
+    SELECT key, value FROM settings
+    WHERE key IN ('slow_endpoint_buffer_ms', 'ttfb_budget_window_ms', 'ttfb_budget_half_life_ms', 'ttfb_budget_min_samples')
+  `).all();
+    const settings = new Map(rows.map(row => [row.key, row.value]));
+    const duration = (key, fallback, allowZero = false) => {
+        for (const raw of [settings.get(key), process.env[key.toUpperCase()]]) {
+            if (raw === undefined || raw.trim() === '')
+                continue;
+            const value = Number(raw);
+            if (Number.isFinite(value) && (allowZero ? value >= 0 : value > 0))
+                return value;
+        }
+        return fallback;
+    };
+    return {
+        bufferMs: duration('slow_endpoint_buffer_ms', DEFAULT_BUFFER_MS, true),
+        windowMs: duration('ttfb_budget_window_ms', DEFAULT_WINDOW_MS),
+        halfLifeMs: duration('ttfb_budget_half_life_ms', DEFAULT_HALF_LIFE_MS),
+        minSamples: duration('ttfb_budget_min_samples', DEFAULT_MIN_SAMPLES),
+    };
+}
+function endpointKey(platform, endpointScope) {
+    // Catalog platforms have one endpoint identity, while custom relays share a
+    // platform and must never inherit each other's latency history.
+    return JSON.stringify([platform, platform === 'custom' ? endpointScopeForBaseUrl(endpointScope) : '']);
+}
+function timestampMs(raw) {
+    // SQLite's datetime('now') has no suffix but is UTC. Date.parse would treat
+    // it as local time; ISO values may already carry Z or an explicit offset.
+    const iso = raw.trim().replace(' ', 'T');
+    return Date.parse(/(?:Z|[+-]\d{2}:?\d{2})$/i.test(iso) ? iso : `${iso}Z`);
+}
+function percentile(samples, totalWeight, quantile) {
+    const target = totalWeight * quantile;
+    let cumulative = 0;
+    for (const sample of samples) {
+        cumulative += sample.weight;
+        if (cumulative >= target)
+            return sample.ttfbMs;
+    }
+    return samples[samples.length - 1].ttfbMs;
+}
+function statsFor(db, config, now) {
+    if (cache?.db === db && cache.windowMs === config.windowMs && cache.halfLifeMs === config.halfLifeMs
+        && now >= cache.time && now - cache.time < CACHE_TTL_MS)
+        return cache.stats;
+    // Keep the created_at range index usable despite SQLite/ISO timestamp
+    // formats. Read one extra UTC day for offset-bearing ISO timestamps, then
+    // enforce the precise sliding window after parsing all timestamps as UTC.
+    const earliest = new Date(now - config.windowMs - 24 * 60 * 60 * 1000);
+    const since = Number.isFinite(earliest.getTime()) ? earliest.toISOString().slice(0, 10) : '';
+    const rows = db.prepare(`
+    SELECT r.platform, r.ttfb_ms, r.created_at, k.base_url
+    FROM requests r
+    LEFT JOIN api_keys k ON k.id = r.key_id AND k.platform = 'custom'
+    WHERE r.created_at >= ? AND r.status = 'success' AND r.ttfb_ms IS NOT NULL
+  `).all(since);
+    const buckets = new Map();
+    for (const row of rows) {
+        if (typeof row.ttfb_ms !== 'number' || !Number.isFinite(row.ttfb_ms) || row.ttfb_ms < 0
+            || typeof row.created_at !== 'string')
+            continue;
+        const age = now - timestampMs(row.created_at);
+        if (!Number.isFinite(age) || age < 0 || age > config.windowMs)
+            continue;
+        const weight = Math.pow(0.5, age / config.halfLifeMs);
+        if (!(weight > 0))
+            continue;
+        const key = endpointKey(row.platform, row.base_url ?? '');
+        let bucket = buckets.get(key);
+        if (!bucket)
+            buckets.set(key, bucket = []);
+        bucket.push({ ttfbMs: row.ttfb_ms, weight });
+    }
+    const stats = new Map();
+    for (const [key, samples] of buckets) {
+        samples.sort((a, b) => a.ttfbMs - b.ttfbMs);
+        const weightedSamples = samples.reduce((total, sample) => total + sample.weight, 0);
+        stats.set(key, {
+            p50Ms: percentile(samples, weightedSamples, 0.5),
+            p95Ms: percentile(samples, weightedSamples, 0.95),
+            sampleCount: samples.length,
+            weightedSamples,
+        });
+    }
+    cache = { db, time: now, windowMs: config.windowMs, halfLifeMs: config.halfLifeMs, stats };
+    return stats;
+}
+/** Decay-weighted nearest-rank percentiles of successful endpoint TTFB. */
+export function getEndpointTtfbStats(platform, endpointScope = '', now = Date.now()) {
+    if (!Number.isFinite(now))
+        return null;
+    try {
+        const db = getDb();
+        const stats = statsFor(db, readConfig(db), now).get(endpointKey(platform, endpointScope));
+        return stats ? { ...stats } : null;
+    }
+    catch {
+        invalidateTtfbBudgetCache();
+        return null;
+    }
+}
+/** Give historically slow endpoints their P95 TTFB plus a safety buffer. */
+export function getEndpointTimeBudgetMs(baseBudgetMs, platform, endpointScope = '', now = Date.now()) {
+    if (!Number.isFinite(baseBudgetMs) || baseBudgetMs <= 0 || !Number.isFinite(now)
+        || process.env.TTFB_BUDGET_DISABLED?.trim() === '1')
+        return baseBudgetMs;
+    try {
+        const db = getDb();
+        const config = readConfig(db);
+        const stats = statsFor(db, config, now).get(endpointKey(platform, endpointScope));
+        if (!stats || stats.p95Ms <= 0 || stats.sampleCount < config.minSamples
+            || stats.p95Ms < baseBudgetMs * SLOW_P95_BASE_FRACTION)
+            return baseBudgetMs;
+        const adaptiveBudget = stats.p95Ms + config.bufferMs;
+        if (!Number.isFinite(adaptiveBudget))
+            return baseBudgetMs;
+        return Math.max(baseBudgetMs, Math.min(adaptiveBudget, baseBudgetMs * MAX_BUDGET_MULTIPLIER));
+    }
+    catch {
+        // Missing/locked DB or a bad log must not break the proxy hot path.
+        invalidateTtfbBudgetCache();
+        return baseBudgetMs;
+    }
+}
+//# sourceMappingURL=ttfb-budget.js.map

package/dist/lib/ttfb-budget.js.map

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

package/dist/lib/url-guard.d.ts

@@ -0,0 +1,47 @@
+export type AddressClass = 'metadata' | 'link-local' | 'loopback' | 'private' | 'public';
+export declare function classifyIp(ip: string): AddressClass;
+/**
+ * Hostname half of {@link isLoopbackOrPrivateUrl}: true when a bare hostname
+ * names THIS machine or the LAN. Callers that already parsed the URL (the
+ * proxy router, which needs the hostname for NO_PROXY anyway) use this
+ * directly so the URL is parsed once.
+ *
+ * Normalises the two spellings a URL hostname can arrive in: IPv6 literals are
+ * bracketed (`[::1]`), and the FQDN form carries a trailing dot (`localhost.`
+ * — a real, resolvable spelling that must not slip past as a public name).
+ */
+export declare function isLoopbackOrPrivateHostname(hostname: string): boolean;
+/**
+ * Synchronous locality check for a stored provider base_url: true when the URL
+ * points at THIS machine or the LAN (loopback, RFC1918/ULA private, 'localhost').
+ * Used by the rate limiter to exempt local inference servers (Ollama/llama.cpp/
+ * LM Studio via the 'custom' platform) from cloud-quota cooldown ladders (#592):
+ * a local box has no quota, so long benches only strand the user's one route.
+ *
+ * Deliberately DNS-free so it can sit on the cooldown hot path: literal IPs and
+ * 'localhost'/'*.localhost' are decidable synchronously; any other hostname
+ * (LAN mDNS names included) is pragmatically treated as NON-local — the worst
+ * case there is the pre-existing conservative bench, never a wrong exemption.
+ */
+export declare function isLoopbackOrPrivateUrl(rawUrl: string | null | undefined): boolean;
+export interface UrlAssessment {
+    allowed: boolean;
+    reason?: string;
+}
+export interface AssessOptions {
+    resolve?: (hostname: string) => Promise<string[]>;
+    blockPrivate?: boolean;
+}
+/**
+ * Assess whether an outbound custom-provider URL is safe to contact.
+ * Never throws on malformed input — a bad URL comes back as {allowed: false}.
+ */
+export declare function assessProviderUrl(rawUrl: string, opts?: AssessOptions): Promise<UrlAssessment>;
+/**
+ * Request-time enforcement: throws when the URL is blocked. Used by
+ * proxyFetch for the custom platform so a base_url that slipped into the DB
+ * (older install, direct DB edit, DNS change after save) still can't reach a
+ * blocked address class.
+ */
+export declare function assertProviderUrlAllowed(rawUrl: string): Promise<void>;
+//# sourceMappingURL=url-guard.d.ts.map

package/dist/lib/url-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-guard.d.ts","sourceRoot":"","sources":["../../src/lib/url-guard.ts"],"names":[],"mappings":"AAqCA,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAyFzF,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,CAKnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQrE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CASjF;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAE5B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAElD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAWD;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAmDxG;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK5E"}