@absol-labs/agent 0.10.0 → 0.11.0

package/src/x402/delivery-oracle.ts

@@ -0,0 +1,285 @@
+import { z } from "zod";
+
+/**
+ * The Metrik delivery signal, as consumed by the x402 facilitator.
+ *
+ * ## Where the signal comes from
+ *
+ * The oracle publishes `GET /services` — one row per `serviceRef`, reduced from
+ * the oracle's own settlement-path verdicts for the active streams of that
+ * service (`streamproof-oracle/src/service-status.ts`). Its three states are
+ * already buyer-favouring at the source: a FRESH failing stream beats a fresh
+ * delivering sibling, and absent/stale evidence is reported as `unverified`
+ * rather than folded into "fine".
+ *
+ * ## Why this module re-checks freshness the oracle already checked
+ *
+ * The oracle's own bound is 5 minutes (`DEFAULT_SERVICE_STATUS_TTL_MS`), which
+ * is a sensible bound for a dashboard and far too loose for a payment gate. On
+ * top of that the HTTP response itself can be cached or served by a stale
+ * replica, and `lastCheckedAt` is the only field that dates the EVIDENCE rather
+ * than the response. So the age of `lastCheckedAt` is re-derived here against
+ * this module's own, much tighter window.
+ *
+ * ## The freshness window: 90 seconds, and why
+ *
+ * The oracle checkpoints every ~15–22 s, and a service's recorded status is
+ * refreshed on that cadence. A window has to be wide enough that ordinary
+ * jitter does not flap the gate, and narrow enough that "verified" still means
+ * "now":
+ *
+ *   - 3 worst-case probe intervals (3 x 22 s = 66 s) absorbs two consecutive
+ *     missed or slow ticks, which is normal operational noise, not evidence of
+ *     a dead service.
+ *   - plus the oracle's own record-and-serve latency and this process's fetch
+ *     round trip, rounded up: **90 s**.
+ *
+ * Tighter (e.g. 30 s) and a single slow tick turns a healthy service's gate
+ * indeterminate. Looser (e.g. the oracle's own 300 s) and a service that died
+ * four minutes ago still reads `delivering`, which is exactly the claim this
+ * gate exists to avoid making.
+ *
+ * Note this window is strictly stricter than the oracle's: a verdict aged
+ * between 90 s and 300 s is `delivering` at the source and `indeterminate`
+ * here.
+ */
+export const DEFAULT_DELIVERY_FRESHNESS_SECONDS = 90;
+
+/** How long a fetched `/services` snapshot may be reused. See `verdictFor`. */
+export const DEFAULT_DELIVERY_SNAPSHOT_TTL_MS = 10_000;
+
+/** Request timeout for the oracle read. Short: this sits in a payment hot path. */
+export const DEFAULT_DELIVERY_ORACLE_TIMEOUT_MS = 4_000;
+
+export const DEFAULT_METRIK_ORACLE_URL = "https://oracle.metrik.live";
+
+/**
+ * Three states, never two.
+ *
+ * `indeterminate` is deliberately NOT collapsed into either of the others: the
+ * facilitator's policy for "no fresh evidence" is a separate, configurable
+ * decision (see `./verified-delivery-facilitator.ts`), and folding it into
+ * `failing` would make Metrik refuse every payment whenever its own oracle is
+ * quiet or unreachable.
+ */
+export type DeliveryVerdict = "delivering" | "failing" | "indeterminate";
+
+/** Why the verdict is what it is — machine-readable, for logs and for tests. */
+export type DeliveryVerdictReason =
+  | "fresh-delivering"
+  | "fresh-failing"
+  | "no-fresh-evidence"
+  | "verdict-stale"
+  | "service-not-listed"
+  | "oracle-unreachable"
+  | "oracle-malformed";
+
+export interface DeliveryAssessment {
+  readonly serviceRef: string;
+  readonly verdict: DeliveryVerdict;
+  readonly reason: DeliveryVerdictReason;
+  /** Unix ms of the newest recorded check for this service, when known. */
+  readonly lastCheckedAt: number | null;
+  /** Age of `lastCheckedAt` in seconds, when known. */
+  readonly ageSeconds: number | null;
+  /** The freshness window applied, in seconds. */
+  readonly freshnessWindowSeconds: number;
+}
+
+export interface MetrikDeliveryOracle {
+  /** Never throws: an unreachable oracle is an `indeterminate` verdict, not an exception. */
+  verdictFor(serviceRef: string): Promise<DeliveryAssessment>;
+}
+
+/** The subset of the oracle's `/services` row this module relies on. */
+const serviceStatusRowSchema = z
+  .object({
+    serviceRef: z.string(),
+    status: z.enum(["delivering", "failing", "unverified"]),
+    lastCheckedAt: z.number().nullable().optional(),
+  })
+  .passthrough();
+
+const servicesResponseSchema = z.object({
+  services: z.array(serviceStatusRowSchema),
+});
+
+export type FetchLike = (
+  input: string,
+  init?: { signal?: AbortSignal; headers?: Record<string, string> },
+) => Promise<{
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+}>;
+
+export interface OracleDeliveryOracleOptions {
+  /** Oracle base URL. Default {@link DEFAULT_METRIK_ORACLE_URL}. */
+  readonly oracleUrl?: string;
+  /** Default {@link DEFAULT_DELIVERY_FRESHNESS_SECONDS}. */
+  readonly freshnessWindowSeconds?: number;
+  /** Default {@link DEFAULT_DELIVERY_SNAPSHOT_TTL_MS}. */
+  readonly snapshotTtlMs?: number;
+  readonly timeoutMs?: number;
+  readonly fetch?: FetchLike;
+  /** Injectable clock (unix ms), for tests. */
+  readonly now?: () => number;
+}
+
+/**
+ * Reads `GET {oracleUrl}/services` and projects one row onto a
+ * {@link DeliveryAssessment}.
+ *
+ * The snapshot is cached for {@link DEFAULT_DELIVERY_SNAPSHOT_TTL_MS} so a burst
+ * of payments does not become a burst of oracle reads. The cache is SHORTER than
+ * the freshness window by design, and caching cannot make a verdict look fresher
+ * than it is: freshness is computed from the row's own `lastCheckedAt`, never
+ * from when we fetched it.
+ */
+export function createOracleDeliveryOracle(
+  options: OracleDeliveryOracleOptions = {},
+): MetrikDeliveryOracle {
+  const oracleUrl = (options.oracleUrl ?? DEFAULT_METRIK_ORACLE_URL).replace(
+    /\/+$/,
+    "",
+  );
+  const freshnessWindowSeconds =
+    options.freshnessWindowSeconds ?? DEFAULT_DELIVERY_FRESHNESS_SECONDS;
+  if (!Number.isFinite(freshnessWindowSeconds) || freshnessWindowSeconds <= 0) {
+    throw new Error("freshnessWindowSeconds must be a positive number");
+  }
+  const snapshotTtlMs =
+    options.snapshotTtlMs ?? DEFAULT_DELIVERY_SNAPSHOT_TTL_MS;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_DELIVERY_ORACLE_TIMEOUT_MS;
+  const doFetch = (options.fetch ??
+    ((input, init) => globalThis.fetch(input, init))) as FetchLike;
+  const now = options.now ?? (() => Date.now());
+
+  type Snapshot = {
+    readonly fetchedAtMs: number;
+    readonly rows: Map<string, z.infer<typeof serviceStatusRowSchema>> | null;
+    readonly failure: DeliveryVerdictReason | null;
+  };
+  let snapshot: Snapshot | undefined;
+  let inFlight: Promise<Snapshot> | undefined;
+
+  async function loadSnapshot(): Promise<Snapshot> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const response = await doFetch(`${oracleUrl}/services`, {
+        signal: controller.signal,
+        headers: { accept: "application/json", "cache-control": "no-cache" },
+      });
+      if (!response.ok) {
+        return {
+          fetchedAtMs: now(),
+          rows: null,
+          failure: "oracle-unreachable",
+        };
+      }
+      const parsed = servicesResponseSchema.safeParse(await response.json());
+      if (!parsed.success) {
+        return { fetchedAtMs: now(), rows: null, failure: "oracle-malformed" };
+      }
+      const rows = new Map<string, z.infer<typeof serviceStatusRowSchema>>();
+      for (const row of parsed.data.services) {
+        rows.set(row.serviceRef.toLowerCase(), row);
+      }
+      return { fetchedAtMs: now(), rows, failure: null };
+    } catch {
+      return { fetchedAtMs: now(), rows: null, failure: "oracle-unreachable" };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async function currentSnapshot(): Promise<Snapshot> {
+    const cached = snapshot;
+    if (cached !== undefined && now() - cached.fetchedAtMs < snapshotTtlMs) {
+      return cached;
+    }
+    // Collapse concurrent misses onto one request.
+    inFlight ??= loadSnapshot().finally(() => {
+      inFlight = undefined;
+    });
+    const loaded = await inFlight;
+    snapshot = loaded;
+    return loaded;
+  }
+
+  return {
+    async verdictFor(serviceRef) {
+      const key = serviceRef.toLowerCase();
+      const loaded = await currentSnapshot();
+      if (loaded.rows === null) {
+        return indeterminate(
+          serviceRef,
+          loaded.failure ?? "oracle-unreachable",
+          null,
+          freshnessWindowSeconds,
+        );
+      }
+      const row = loaded.rows.get(key);
+      if (row === undefined) {
+        return indeterminate(
+          serviceRef,
+          "service-not-listed",
+          null,
+          freshnessWindowSeconds,
+        );
+      }
+      const lastCheckedAt = row.lastCheckedAt ?? null;
+      const ageSeconds =
+        lastCheckedAt === null
+          ? null
+          : Math.max(0, Math.round((now() - lastCheckedAt) / 1000));
+
+      if (row.status === "unverified") {
+        return indeterminate(
+          serviceRef,
+          "no-fresh-evidence",
+          lastCheckedAt,
+          freshnessWindowSeconds,
+          ageSeconds,
+        );
+      }
+      // The oracle dated its own verdict; if it cannot be shown to be recent it
+      // is not evidence of anything, in EITHER direction.
+      if (ageSeconds === null || ageSeconds > freshnessWindowSeconds) {
+        return indeterminate(
+          serviceRef,
+          "verdict-stale",
+          lastCheckedAt,
+          freshnessWindowSeconds,
+          ageSeconds,
+        );
+      }
+      return {
+        serviceRef,
+        verdict: row.status === "failing" ? "failing" : "delivering",
+        reason: row.status === "failing" ? "fresh-failing" : "fresh-delivering",
+        lastCheckedAt,
+        ageSeconds,
+        freshnessWindowSeconds,
+      };
+    },
+  };
+}
+
+function indeterminate(
+  serviceRef: string,
+  reason: DeliveryVerdictReason,
+  lastCheckedAt: number | null,
+  freshnessWindowSeconds: number,
+  ageSeconds: number | null = null,
+): DeliveryAssessment {
+  return {
+    serviceRef,
+    verdict: "indeterminate",
+    reason,
+    lastCheckedAt,
+    ageSeconds,
+    freshnessWindowSeconds,
+  };
+}

package/src/x402/facilitator-server-entry.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { startMetrikFacilitatorServerFromEnv } from "./facilitator-server.js";
+
+/**
+ * Runnable entrypoint for Metrik's x402 facilitator (`metrik-x402-facilitator`).
+ * All configuration comes from the environment; see
+ * {@link parseMetrikFacilitatorEnvConfig}. Refuses to start without a
+ * settlement relayer unless `METRIK_X402_ALLOW_VERIFY_ONLY=true`.
+ */
+async function main(): Promise<void> {
+  const server = await startMetrikFacilitatorServerFromEnv();
+  const host = process.env.METRIK_X402_HOST ?? "0.0.0.0";
+  console.error(
+    `[metrik-x402-facilitator] listening on http://${host}:${server.boundPort}`,
+  );
+
+  const shutdown = (signal: string) => {
+    console.error(
+      `[metrik-x402-facilitator] ${signal} received — shutting down`,
+    );
+    server
+      .close()
+      .then(() => process.exit(0))
+      .catch(() => process.exit(1));
+  };
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+}
+
+main().catch((error) => {
+  console.error(
+    error instanceof Error ? error.message : "failed to start x402 facilitator",
+  );
+  process.exit(1);
+});