agentex-creator-sdk 1.0.0

package/dist/packages/providers/src/health.d.ts

@@ -0,0 +1,273 @@
+import { z } from 'zod';
+/**
+ * E04 provider health: stale-head detection, bounded retries, semantics-preserving failover, a public-data cache and operator
+ * telemetry. Owner rule: nothing waits for or gates on finality. Freshness compares the provider's head (the `latest` block time
+ * on EVM, the `confirmed` slot's block time on Solana) with the wall clock; a head that stops advancing is stale. There is no
+ * finality-lag check. Endpoints are identified by host only; URLs with paths, queries or credentials never leave this module.
+ */
+export interface RpcRequestTransport {
+    request(method: string, params: readonly unknown[], signal: AbortSignal): Promise<unknown>;
+}
+export declare const ProviderHealthCategorySchema: z.ZodEnum<{
+    "provider-unavailable": "provider-unavailable";
+    "history-unavailable": "history-unavailable";
+    "rate-limited": "rate-limited";
+    timeout: "timeout";
+    cancelled: "cancelled";
+    "invalid-response": "invalid-response";
+    "chain-mismatch": "chain-mismatch";
+    "provider-stale": "provider-stale";
+    "snapshot-mismatch": "snapshot-mismatch";
+    "request-rejected": "request-rejected";
+    "execution-result": "execution-result";
+}>;
+export type ProviderHealthCategory = z.infer<typeof ProviderHealthCategorySchema>;
+export declare class ProviderHealthError extends Error {
+    readonly category: ProviderHealthCategory;
+    constructor(category: ProviderHealthCategory, message: string);
+}
+/** The caller's `beforeAttempt` permit refused an attempt. It is never retried or failed over; `original` is the caller's error. */
+export declare class AttemptRefusedError extends ProviderHealthError {
+    readonly original: unknown;
+    constructor(original: unknown);
+}
+/**
+ * Optionally returned by a `beforeAttempt` permit for hidden provider work (retries, identity checks, cross-checks, freshness probes). It is
+ * called once with the attempt's observed outcome, so the runtime can settle that permit; hidden work produces no tool evidence of its own.
+ * Primary requests return nothing: the tool records their result as evidence.
+ */
+export type AttemptCompletion = (result: {
+    outcome: 'success' | ProviderHealthCategory;
+}) => void | Promise<void>;
+/** `headTag` is the head runs read; `maximumHeadAgeSeconds` bounds that head's age against the wall clock. */
+export interface HeadFreshnessPolicy {
+    family: 'evm' | 'solana';
+    identity: string;
+    headTag: 'latest' | 'confirmed';
+    maximumHeadAgeSeconds: number;
+    observedTypicalHeadAge: string;
+    observedAt: string;
+}
+/** Thresholds leave wide margin over each chain's block interval so a merely slow endpoint is not excluded; only a head that stopped advancing is. */
+export declare const HEAD_FRESHNESS_POLICIES: Readonly<Record<string, HeadFreshnessPolicy>>;
+export declare const endpointHost: (url: string) => string;
+export declare function categorizeProviderError(error: unknown, signal?: AbortSignal): ProviderHealthCategory;
+/** Relative request weight for budgeting. It is not a price: every free public source remains unpriced. */
+export declare const methodCostUnits: (method: string) => number;
+export type AttemptPurpose = 'request' | 'identity' | 'cross-check' | 'freshness-probe';
+interface EndpointStats {
+    id: string;
+    chain: string;
+    host: string;
+    status: 'unobserved' | 'healthy' | 'degraded' | 'provider-stale' | 'excluded';
+    lastCategory: ProviderHealthCategory | null;
+    lastObservedAt: string | null;
+    requests: number;
+    successes: number;
+    failures: Partial<Record<ProviderHealthCategory, number>>;
+    retries: number;
+    failovers: number;
+    identityChecks: number;
+    crossChecks: number;
+    crossCheckMismatches: number;
+    cacheHits: number;
+    costUnits: number;
+    latencyTotalMs: number;
+    latencyMaxMs: number;
+    lastLatencyMs: number | null;
+    freshness: {
+        headAgeSeconds: number | null;
+        thresholdSeconds: number | null;
+        observedAt: string;
+    } | null;
+}
+export declare class ProviderTelemetry {
+    #private;
+    attempt(endpoint: {
+        id: string;
+        chain: string;
+        host: string;
+    }, event: {
+        method: string;
+        outcome: 'success' | ProviderHealthCategory;
+        latencyMs: number;
+        purpose: AttemptPurpose;
+        retry?: boolean;
+        at?: Date;
+    }): void;
+    mark(endpoint: {
+        id: string;
+        chain: string;
+        host: string;
+    }, status: EndpointStats['status'], category: ProviderHealthCategory | null): void;
+    failover(endpoint: {
+        id: string;
+        chain: string;
+        host: string;
+    }): void;
+    crossCheckMismatch(endpoint: {
+        id: string;
+        chain: string;
+        host: string;
+    }): void;
+    cacheHit(endpoint: {
+        id: string;
+        chain: string;
+        host: string;
+    } | null): void;
+    cacheMiss(): void;
+    cacheStore(): void;
+    cachePrivateRefusal(): void;
+    freshness(endpoint: {
+        id: string;
+        chain: string;
+        host: string;
+    }, observation: NonNullable<EndpointStats['freshness']> & {
+        stale: boolean;
+    }): void;
+    snapshot(now?: Date): {
+        schemaVersion: "agentex.provider-health.v1";
+        generatedAt: string;
+        costStatus: "unpriced";
+        note: string;
+        cache: {
+            hits: number;
+            misses: number;
+            stores: number;
+            rejectedPrivate: number;
+            scope: "public-chain-data-only";
+        };
+        endpoints: {
+            meanLatencyMs: number | null;
+            id: string;
+            chain: string;
+            host: string;
+            status: "unobserved" | "healthy" | "degraded" | "provider-stale" | "excluded";
+            lastCategory: ProviderHealthCategory | null;
+            lastObservedAt: string | null;
+            requests: number;
+            successes: number;
+            failures: Partial<Record<ProviderHealthCategory, number>>;
+            retries: number;
+            failovers: number;
+            identityChecks: number;
+            crossChecks: number;
+            crossCheckMismatches: number;
+            cacheHits: number;
+            costUnits: number;
+            latencyTotalMs: number;
+            latencyMaxMs: number;
+            lastLatencyMs: number | null;
+            freshness: {
+                headAgeSeconds: number | null;
+                thresholdSeconds: number | null;
+                observedAt: string;
+            } | null;
+        }[];
+    };
+    reset(): void;
+}
+/** Process-wide operator telemetry. It holds hosts, counters and freshness only: no request parameters, results or tenant identifiers. */
+export declare const PROVIDER_TELEMETRY: ProviderTelemetry;
+/** The block number a state request is pinned to, or null for moving tags and unpinned requests. */
+export declare function referencedBlockNumber(method: string, params: readonly unknown[]): bigint | null;
+export interface CacheContext {
+    chain: string;
+    family: 'evm' | 'solana';
+    identity: string;
+    anchors: ReadonlyMap<string, {
+        hash: string;
+    }>;
+}
+/**
+ * Shared cache key for public chain data only. Reads are not final, so a key always binds the exact block hash this transport observed
+ * at the referenced height: a reorg changes the hash and therefore the key. Block headers are never cached (they are the reorg check),
+ * Solana data is never cached (confirmed data can still roll back), and proposed payloads, sender-context calls, moving tags and unpinned
+ * reads are never cacheable, so one tenant's private request cannot be served to another.
+ */
+export declare function publicCacheKey(context: CacheContext, method: string, params: readonly unknown[]): string | null;
+export declare class PublicDataCache {
+    #private;
+    readonly maximumEntries: number;
+    readonly maximumBytes: number;
+    readonly maximumEntryBytes: number;
+    constructor(maximumEntries?: number, maximumBytes?: number, maximumEntryBytes?: number);
+    get(key: string): unknown;
+    set(key: string, value: unknown): boolean;
+    get size(): number;
+    clear(): void;
+}
+export declare const PUBLIC_DATA_CACHE: PublicDataCache;
+export interface ResilientEndpoint {
+    id: string;
+    url: string;
+    transport: RpcRequestTransport;
+    /** Methods this endpoint serves; others never reach it (a keyless node that serves no debug namespace, for example). Defaults to all. */
+    serves?: (method: string, params: readonly unknown[]) => boolean;
+    /** Requests this endpoint should answer first (a trace, or a log range wider than public nodes serve), before the usual order. */
+    prefers?: (method: string, params: readonly unknown[]) => boolean;
+}
+export interface ResilientTransportOptions {
+    chain: string;
+    endpoints: readonly ResilientEndpoint[];
+    /** Attempts per logical request across endpoints (1-3). Defaults to 1 for one endpoint and 2 with failover. */
+    maximumAttempts?: number;
+    /** Extra attempts, identity checks and snapshot cross-checks shared by the transport's lifetime (0-16). */
+    retryBudget?: number;
+    cache?: PublicDataCache | null;
+    telemetry?: ProviderTelemetry;
+    now?: () => Date;
+    backoffMs?: number;
+    /** Runtime permit hook for every network attempt, including retries and cross-checks, so hidden work cannot bypass run budgets. */
+    beforeAttempt?: (operation: {
+        endpointId: string;
+        method: string;
+        purpose: AttemptPurpose;
+        attempt: number;
+    }) => void | AttemptCompletion | Promise<void | AttemptCompletion>;
+    categorize?: (error: unknown, signal: AbortSignal) => ProviderHealthCategory;
+}
+export interface ResilientTransport extends RpcRequestTransport {
+    health(): {
+        id: string;
+        host: string;
+        excluded: ProviderHealthCategory | null;
+        identity: 'unverified' | 'verified' | 'mismatch';
+    }[];
+    readonly retryBudgetRemaining: number;
+    /** The endpoint that answered the most recent successful request (a cache hit names the endpoint that first served it), for evidence attribution. */
+    servedBy(): {
+        id: string;
+        host: string;
+    } | null;
+}
+export declare function createResilientTransport(options: ResilientTransportOptions): ResilientTransport;
+export interface FreshnessObservation {
+    chain: string;
+    host: string;
+    observedAt: string;
+    status: 'healthy' | ProviderHealthCategory;
+    identity: string | null;
+    expectedIdentity: string;
+    /** The head runs read: `latest` on EVM, the `confirmed` slot on Solana. */
+    tag: 'latest' | 'confirmed';
+    head: {
+        number: string;
+        hash: string | null;
+        timestamp: string | null;
+    } | null;
+    headAgeSeconds: number | null;
+    thresholdSeconds: number;
+    requests: number;
+}
+/** Active three-call head freshness probe for operators and verification scripts: identity, the head and its age. No finality is read. */
+export declare function probeFreshness(chain: string, endpoint: {
+    id: string;
+    url: string;
+    transport: RpcRequestTransport;
+}, options?: {
+    signal?: AbortSignal;
+    now?: () => Date;
+    telemetry?: ProviderTelemetry;
+}): Promise<FreshnessObservation>;
+export {};