@absol-labs/agent 0.5.0 → 0.6.0

package/src/discovery/registry.ts

@@ -1,7 +1,11 @@
 import {
   deriveServiceRef,
   recoverServiceBindingSigner,
+  recoverServiceDescriptorSigner,
   serviceBindingSchema,
+  serviceDescriptorSchema,
+  type SignedServiceBinding,
+  type SignedServiceDescriptor,
 } from "@absol-labs/shared";
 import { isHex } from "viem";
 import { z } from "zod";
@@ -35,9 +39,14 @@ export interface ServiceListing {
   readonly serviceRef: `0x${string}`;
   readonly operator: `0x${string}`;
   readonly publicUrl: string;
+  readonly access: "public" | "gated";
+  /** Signed invocation origin; gated listings fail closed if this is absent. */
+  readonly accessUrl: string;
+  /** The schema-validated and cryptographically verified signed record. */
+  readonly signed: SignedServiceBinding | SignedServiceDescriptor;
   /** Unsigned informational category from the listings row (may be absent). */
   readonly category: string | null;
-  /** Optional signed operator-supplied target metadata (e.g. resolver hints). */
+  /** Optional unsigned operator-supplied resolver hints; never used for invocation. */
   readonly targetMetadata?: Record<string, string>;
 }
 
@@ -76,14 +85,16 @@ export const DEFAULT_METRIK_REGISTRY_URL =
 const DEFAULT_TIMEOUT_MS = 5_000;
 
 /**
- * `serviceRef` of the built-in verified demo listing. Kept as a named constant so
+ * `serviceRef` of the built-in verified live-data listing. Kept as a named constant so
  * callers can recognise (and dedupe against) the seeded row.
  */
-export const DEMO_SEED_SERVICE_REF =
-  "0x84ef78c5ac9fc084422dc2d3e1ef19623bb05d0d81c097d4da49f9c47ec3ed12" as const;
+export const LIVE_DATA_SEED_SERVICE_REF =
+  "0x79e57358e98a35273c1cd9d5f1bf9ae1e0af8705db432eb706459dc4f88b6fe0" as const;
+/** @deprecated Use {@link LIVE_DATA_SEED_SERVICE_REF}. */
+export const DEMO_SEED_SERVICE_REF = LIVE_DATA_SEED_SERVICE_REF;
 
 /**
- * A REAL, operator-signed demo listing row embedded so `discoverServices()` returns
+ * A real, operator-signed live-data listing row embedded so `discoverServices()` returns
  * something hireable with ZERO configuration (no Supabase anon key, no registry URL).
  *
  * This is PUBLIC data — a signed {@link https://github.com/Absol-Labs | Metrik}
@@ -94,23 +105,115 @@ export const DEMO_SEED_SERVICE_REF =
  * with any field here and the seed silently drops itself, identically to a bad
  * registry row. The `category` column is unsigned informational metadata only.
  */
-export const DEMO_SEED_LISTING = {
-  service_ref: DEMO_SEED_SERVICE_REF,
-  operator: "0x28ea4eF61ac4cca3ed6a64dBb5b2D4be1aDC9814",
-  public_url: "https://metrik-demo-service.vercel.app",
-  category: "demo",
+export const LIVE_DATA_SEED_LISTING = {
+  service_ref: LIVE_DATA_SEED_SERVICE_REF,
+  operator: "0xB3e162711920dFD8933609019Dc35C73cC1a09F0",
+  public_url: "https://livedata.137.23.50.249.sslip.io",
+  category: "live-data",
   signed_binding: {
-    serviceRef: DEMO_SEED_SERVICE_REF,
-    binding: {
-      version: 2,
-      operator: "0x28ea4eF61ac4cca3ed6a64dBb5b2D4be1aDC9814",
-      publicUrl: "https://metrik-demo-service.vercel.app",
-      issuedAt: 1_787_500_000,
+    serviceRef: LIVE_DATA_SEED_SERVICE_REF,
+    descriptor: {
+      version: 3,
+      operator: "0xB3e162711920dFD8933609019Dc35C73cC1a09F0",
+      publicUrl: "https://livedata.137.23.50.249.sslip.io",
+      issuedAt: 1_787_772_057,
+      interface: {
+        baseUrl: "https://livedata.137.23.50.249.sslip.io",
+        healthPath: "/health",
+        endpoints: [
+          {
+            name: "health",
+            path: "/health",
+            method: "GET",
+            description: "Liveness probe.",
+          },
+          {
+            name: "readiness",
+            path: "/readiness",
+            method: "GET",
+            description:
+              "Non-value dependency readiness backed by the same real BTC cache policy.",
+          },
+          {
+            name: "price",
+            path: "/price",
+            method: "GET",
+            description:
+              "Real live crypto spot price (?symbol=BTC|ETH|SOL) from CoinGecko's public API.",
+          },
+        ],
+        authModel: "caller-auth",
+        example: {
+          endpoint: "price",
+          request: { symbol: "BTC" },
+          response: { symbol: "BTC", source: "coingecko-public-api" },
+          description:
+            "Real, nondeterministic live price — no re-execution guarantee.",
+        },
+        expectedStatuses: [200],
+      },
+      verification: {
+        canaries: [
+          {
+            path: "/readiness",
+            method: "GET",
+            matcher: {
+              type: "json-field-equals",
+              field: "source",
+              expected: "coingecko-public-api",
+            },
+            nonce: {
+              inject: { in: "query", name: "nonce" },
+              echo: { from: "json-path", path: "nonce" },
+            },
+          },
+          {
+            path: "/canary",
+            method: "GET",
+            matcher: {
+              type: "includes",
+              expected: "metrik-canary:live-data:",
+            },
+            nonce: {
+              inject: { in: "query", name: "nonce" },
+              echo: { from: "json-path", path: "nonce" },
+            },
+          },
+        ],
+        schema: {
+          path: "/readiness?nonce=metrik-schema",
+          required: [
+            { pointer: "ready", type: "boolean" },
+            { pointer: "source", type: "string", nonEmpty: true },
+            { pointer: "fetchedAt", type: "string", nonEmpty: true },
+            { pointer: "priceAgeMs", type: "number" },
+            { pointer: "freshness", type: "string", nonEmpty: true },
+          ],
+        },
+        sla: { maxLatencyMs: 5000, freshnessSeconds: 60 },
+      },
+      commercial: {
+        minRatePerSecond: "100",
+        maxRatePerSecond: "10000",
+        currency: "USDC",
+        slaDescription:
+          "Failed or unproven intervals do not advance verified cumulative entitlement; the stream remains active until buyer close or expiry.",
+        refundPolicy:
+          "The buyer reclaims unspent escrow using the latest checkpoint after close/expiry, or the unverified escape path after its grace window.",
+      },
+      access: "gated",
+      callerAuth: {
+        mechanism: "on-chain",
+        role: "buyer",
+        accessUrl: "https://gateway.137.23.50.249.sslip.io",
+      },
     },
     signature:
-      "0x17917e96836a63238d0abe70c8c55081c4d694ad43311cdb3ea91dad349827fa6480657be2362e0b7f0524a0ee4ba0c48068255c3423a965392724874d244cd21b",
+      "0x2f4d2784eb40b1542517bc19f12534fb2e97da4ade5a3ff56193fcfb97fbef921309f77af3445e336cb07a4379011b080bba700033a098f672b0b2f096197f161b",
   },
 } as const;
+/** @deprecated Use {@link LIVE_DATA_SEED_LISTING}. */
+export const DEMO_SEED_LISTING = LIVE_DATA_SEED_LISTING;
 
 const signature65HexSchema = z
   .string()
@@ -135,12 +238,25 @@ const signedBindingRecordSchema = z.object({
   targetMetadata: z.record(z.string()).optional(),
 });
 
+const signedDescriptorRecordSchema = z.object({
+  serviceRef: bytes32HexSchema,
+  descriptor: serviceDescriptorSchema,
+  signature: signature65HexSchema,
+  targetMetadata: z.record(z.string()).optional(),
+});
+
 /** A Supabase `listings` row. Only `signed_binding` is trusted; `category` is
  * carried through as unsigned informational metadata. Unknown columns are ignored. */
 const listingRowSchema = z
   .object({
+    service_ref: bytes32HexSchema.optional(),
+    operator: z.string().optional(),
+    public_url: z.string().optional(),
     category: z.string().nullish(),
-    signed_binding: signedBindingRecordSchema,
+    signed_binding: z.union([
+      signedBindingRecordSchema,
+      signedDescriptorRecordSchema,
+    ]),
   })
   .passthrough();
 
@@ -167,13 +283,13 @@ export async function discoverServices(
 
   // `registryUnavailable` = the registry could not be queried at all (no fetch /
   // network error / non-200). It never throws into the hire flow; instead it
-  // degrades to the built-in verified demo seed (when enabled) so a cold user
+  // degrades to the built-in verified live-data seed (when enabled) so a cold user
   // still discovers a hireable service.
   let rows: unknown[] = [];
   let registryUnavailable = false;
   if (typeof fetchImpl !== "function") {
     logger.warn(
-      "metrik discovery: no fetch implementation available; falling back to demo seed only",
+      "metrik discovery: no fetch implementation available; falling back to live-data seed only",
     );
     registryUnavailable = true;
   } else {
@@ -182,9 +298,9 @@ export async function discoverServices(
     } catch (error) {
       // Fail-safe / buyer-favouring: a down, unreachable, or 401 registry (the
       // Supabase default rejects credential-free reads) must never throw into the
-      // agent's hire flow — it degrades to the demo seed.
+      // agent's hire flow — it degrades to the live-data seed.
       logger.warn(
-        `metrik discovery: listings registry unavailable (${errorMessage(error)}); falling back to demo seed only`,
+        `metrik discovery: listings registry unavailable (${errorMessage(error)}); falling back to live-data seed only`,
       );
       registryUnavailable = true;
     }
@@ -210,21 +326,21 @@ export async function discoverServices(
     }
   }
 
-  // Append the built-in verified demo listing when the registry did not already
+  // Append the built-in verified live-data listing when the registry did not already
   // surface it. Runs through the SAME fail-closed verifyRow path, so it is
   // verified exactly like a registry row and can never be a trust bypass.
   if (includeDemoSeed && !seedAlreadyPresent) {
-    const seed = await verifyRow(DEMO_SEED_LISTING, "demo-seed", logger);
+    const seed = await verifyRow(DEMO_SEED_LISTING, "live-data-seed", logger);
     if (seed === null) {
       // Defensive: only reachable if the embedded constant were corrupted.
       logger.warn(
-        "metrik discovery: built-in demo seed failed fail-closed verification; not seeding",
+        "metrik discovery: built-in live-data seed failed fail-closed verification; not seeding",
       );
     } else if (opts.category === undefined || seed.category === opts.category) {
       logger.warn(
         registryUnavailable
-          ? "metrik discovery: registry unavailable — serving the built-in verified demo listing"
-          : "metrik discovery: registry did not include the demo service — appending the built-in verified demo listing",
+          ? "metrik discovery: registry unavailable — serving the built-in verified live-data listing"
+          : "metrik discovery: registry did not include live data — appending the built-in verified listing",
       );
       listings.push(seed);
     }
@@ -284,26 +400,59 @@ async function verifyRow(
   }
   const { signed_binding: record, category } = parsed.data;
 
+  const signedIdentity =
+    "descriptor" in record
+      ? {
+          operator: record.descriptor.operator,
+          publicUrl: record.descriptor.publicUrl,
+        }
+      : {
+          operator: record.binding.operator,
+          publicUrl: record.binding.publicUrl,
+        };
+  if (
+    (parsed.data.service_ref !== undefined &&
+      !eqHex(parsed.data.service_ref, record.serviceRef)) ||
+    (parsed.data.operator !== undefined &&
+      !eqHex(parsed.data.operator, signedIdentity.operator)) ||
+    (parsed.data.public_url !== undefined &&
+      parsed.data.public_url !== signedIdentity.publicUrl)
+  ) {
+    logger.warn(
+      `metrik discovery: row ${index} dropped — flat identity columns disagree with signed record`,
+    );
+    return null;
+  }
+
   let signer: `0x${string}` | null;
   try {
-    signer = (await recoverServiceBindingSigner(
-      record.binding,
-      record.signature as `0x${string}`,
-    )) as `0x${string}` | null;
+    signer = (
+      "descriptor" in record
+        ? await recoverServiceDescriptorSigner(
+            record.descriptor,
+            record.signature as `0x${string}`,
+          )
+        : await recoverServiceBindingSigner(
+            record.binding,
+            record.signature as `0x${string}`,
+          )
+    ) as `0x${string}` | null;
   } catch (error) {
     logger.warn(
       `metrik discovery: row ${index} dropped — signature recovery threw (${errorMessage(error)})`,
     );
     return null;
   }
-  if (signer === null || !eqHex(signer, record.binding.operator)) {
+  if (signer === null || !eqHex(signer, signedIdentity.operator)) {
     logger.warn(
       `metrik discovery: row ${index} dropped — signature does not recover to operator (recovered ${signer ?? "null"})`,
     );
     return null;
   }
 
-  const derivedRef = deriveServiceRef(record.binding);
+  const derivedRef = deriveServiceRef(
+    "descriptor" in record ? record.descriptor : record.binding,
+  );
   if (!eqHex(derivedRef, record.serviceRef)) {
     logger.warn(
       `metrik discovery: row ${index} dropped — serviceRef ${record.serviceRef} does not match derived ${derivedRef}`,
@@ -311,10 +460,31 @@ async function verifyRow(
     return null;
   }
 
+  const access =
+    "descriptor" in record ? (record.descriptor.access ?? "public") : "public";
+  const accessUrl =
+    "descriptor" in record
+      ? access === "gated"
+        ? record.descriptor.callerAuth?.accessUrl
+        : (record.descriptor.interface?.baseUrl ?? record.descriptor.publicUrl)
+      : record.binding.publicUrl;
+  if (
+    accessUrl === undefined ||
+    (access === "gated" && !isHttpsUrl(accessUrl))
+  ) {
+    logger.warn(
+      `metrik discovery: row ${index} dropped — gated descriptor has no signed HTTPS callerAuth.accessUrl`,
+    );
+    return null;
+  }
+
   return {
     serviceRef: derivedRef,
-    operator: record.binding.operator as `0x${string}`,
-    publicUrl: record.binding.publicUrl,
+    operator: signedIdentity.operator as `0x${string}`,
+    publicUrl: signedIdentity.publicUrl,
+    access,
+    accessUrl,
+    signed: record as SignedServiceBinding | SignedServiceDescriptor,
     category: category ?? null,
     ...(record.targetMetadata === undefined
       ? {}
@@ -322,6 +492,14 @@ async function verifyRow(
   };
 }
 
+function isHttpsUrl(value: string): boolean {
+  try {
+    return new URL(value).protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
 function eqHex(a: string, b: string): boolean {
   return a.toLowerCase() === b.toLowerCase();
 }

package/src/frameworks/agentkit.ts

@@ -290,7 +290,7 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
     }
     const lines = listings.map(
       (listing) =>
-        `- ${listing.serviceRef} operator=${listing.operator} url=${listing.publicUrl}${listing.category ? ` category=${listing.category}` : ""}`,
+        `- ${listing.serviceRef} operator=${listing.operator} verificationUrl=${listing.publicUrl} access=${listing.access} accessUrl=${listing.accessUrl}${listing.category ? ` category=${listing.category}` : ""}`,
     );
     return (
       `Discovered ${listings.length} verified Metrik service${listings.length === 1 ? "" : "s"} ` +

package/src/frameworks/crewai.ts

@@ -72,7 +72,7 @@ export function renderCrewAiVerifiedStreamPythonExample(
     "",
     "buyer_agent = Agent(",
     '    role="Verified Compute Buyer",',
-    '    goal="Hire a verified service and stop work when the stream pauses.",',
+    '    goal="Hire a verified service and close it if delivery is no longer verified.",',
     '    backstory="An operator that only pays for oracle-verified delivery.",',
     "    mcps=[metrik_mcp],",
     ")",

package/src/gateway/caller-auth-gateway.ts

@@ -145,6 +145,8 @@ export interface CallerAuthGatewayConfig {
   readonly rpcUrl?: string;
   /** The service this gateway fronts. Every request's stream AND capability must match it. */
   readonly serviceRef: Hex;
+  /** Additional service refs accepted during signed-descriptor migrations. */
+  readonly serviceRefs?: readonly Hex[];
   /** Chain id for EIP-712 domain separation. Default `84532` (Base Sepolia). */
   readonly chainId?: number;
   /** Capability header name. Default {@link CAPABILITY_HEADER_NAME}. */
@@ -176,18 +178,18 @@ export class CallerAuthGateway {
   private readonly nonceCache: NonceReplayCache;
   private readonly headerName: string;
   private readonly domain: InvocationCapabilityDomainInput;
-  private readonly serviceRef: Hex;
+  private readonly serviceRefs: ReadonlySet<string>;
   private readonly now: () => number;
 
   constructor(config: CallerAuthGatewayConfig) {
     if (!isAddress(config.escrowAddress)) {
       throw new Error("escrowAddress must be an EVM address");
     }
-    if (
-      !isHex(config.serviceRef, { strict: true }) ||
-      config.serviceRef.length !== 66
-    ) {
-      throw new Error("serviceRef must be a 32-byte hex value");
+    const serviceRefs = [config.serviceRef, ...(config.serviceRefs ?? [])];
+    for (const serviceRef of serviceRefs) {
+      if (!isHex(serviceRef, { strict: true }) || serviceRef.length !== 66) {
+        throw new Error("every serviceRef must be a 32-byte hex value");
+      }
     }
     if (config.streamReader === undefined && config.rpcUrl === undefined) {
       throw new Error(
@@ -195,7 +197,7 @@ export class CallerAuthGateway {
       );
     }
 
-    this.serviceRef = config.serviceRef;
+    this.serviceRefs = new Set(serviceRefs.map((value) => value.toLowerCase()));
     this.headerName = (
       config.headerName ?? CAPABILITY_HEADER_NAME
     ).toLowerCase();
@@ -260,7 +262,7 @@ export class CallerAuthGateway {
       return deny("path-mismatch", 403, capability);
     }
 
-    if (capability.serviceRef.toLowerCase() !== this.serviceRef.toLowerCase()) {
+    if (!this.serviceRefs.has(capability.serviceRef.toLowerCase())) {
       return deny("service-ref-mismatch", 403, capability);
     }
 
@@ -280,7 +282,9 @@ export class CallerAuthGateway {
     if (stream.buyer.toLowerCase() !== capability.buyer.toLowerCase()) {
       return deny("buyer-mismatch", 403, capability);
     }
-    if (stream.serviceRef.toLowerCase() !== this.serviceRef.toLowerCase()) {
+    if (
+      stream.serviceRef.toLowerCase() !== capability.serviceRef.toLowerCase()
+    ) {
       return deny("service-ref-mismatch", 403, capability);
     }
     if (stream.status !== "active") {

package/src/gateway/http-server.ts

@@ -232,6 +232,7 @@ export interface CallerAuthGatewayEnvConfig {
   readonly escrowAddress: Address;
   readonly rpcUrl: string;
   readonly serviceRef: Hex;
+  readonly serviceRefs: readonly Hex[];
   readonly chainId: number;
   readonly upstreamUrl: string;
   readonly headerName?: string;
@@ -242,7 +243,8 @@ export interface CallerAuthGatewayEnvConfig {
  * - `METRIK_GATEWAY_ESCROW_ADDRESS` (required) - the `StreamEscrowV2` this
  *   gateway checks streams against.
  * - `METRIK_GATEWAY_RPC_URL` (required) - RPC used for the read-only stream check.
- * - `METRIK_GATEWAY_SERVICE_REF` (required) - bytes32 `serviceRef` this gateway fronts.
+ * - `METRIK_GATEWAY_SERVICE_REF` (required) - primary bytes32 service ref.
+ * - `METRIK_GATEWAY_SERVICE_REFS` (optional) - comma-separated migration aliases.
  * - `METRIK_GATEWAY_UPSTREAM_URL` (required) - the real service to proxy to on pass.
  * - `METRIK_GATEWAY_CHAIN_ID` (optional) - default `84532` (Base Sepolia).
  * - `METRIK_GATEWAY_HEADER_NAME` (optional) - default `x-metrik-capability`.
@@ -263,6 +265,17 @@ export function parseCallerAuthGatewayEnvConfig(
   if (!isHex(serviceRef, { strict: true }) || serviceRef.length !== 66) {
     throw new Error("METRIK_GATEWAY_SERVICE_REF must be a 32-byte hex value");
   }
+  const serviceRefs = (env.METRIK_GATEWAY_SERVICE_REFS ?? "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0);
+  for (const candidate of serviceRefs) {
+    if (!isHex(candidate, { strict: true }) || candidate.length !== 66) {
+      throw new Error(
+        "METRIK_GATEWAY_SERVICE_REFS must contain only 32-byte hex values",
+      );
+    }
+  }
   const upstreamUrl = requireEnv(env, "METRIK_GATEWAY_UPSTREAM_URL");
   // eslint-disable-next-line no-new -- validates the URL is well-formed.
   new URL(upstreamUrl);
@@ -288,6 +301,9 @@ export function parseCallerAuthGatewayEnvConfig(
     escrowAddress,
     rpcUrl,
     serviceRef,
+    serviceRefs: [
+      ...new Set(serviceRefs.map((value) => value.toLowerCase())),
+    ] as Hex[],
     chainId,
     upstreamUrl,
     ...(headerName === undefined ? {} : { headerName }),
@@ -311,6 +327,7 @@ export async function startCallerAuthGatewayServerFromEnv(
     escrowAddress: config.escrowAddress,
     rpcUrl: config.rpcUrl,
     serviceRef: config.serviceRef,
+    serviceRefs: config.serviceRefs,
     chainId: config.chainId,
     ...(config.headerName === undefined
       ? {}

package/src/index.ts

@@ -49,6 +49,8 @@ export {
   DEFAULT_METRIK_REGISTRY_URL,
   DEMO_SEED_LISTING,
   DEMO_SEED_SERVICE_REF,
+  LIVE_DATA_SEED_LISTING,
+  LIVE_DATA_SEED_SERVICE_REF,
   discoverServices,
   type DiscoverServicesOptions,
   type ServiceListing,
@@ -219,6 +221,9 @@ export {
 
 export {
   InvokeBuyerMismatchError,
+  InvokeAccessUrlError,
+  InvokePathError,
+  InvokeServiceRefMismatchError,
   InvokeStreamExpiredError,
   InvokeStreamNotActiveError,
   capabilityFor,

package/src/mcp/server.ts

@@ -923,6 +923,8 @@ function serializeServiceListing(
     serviceRef: listing.serviceRef,
     operator: listing.operator,
     publicUrl: listing.publicUrl,
+    access: listing.access,
+    accessUrl: listing.accessUrl,
     category: listing.category,
     ...(listing.targetMetadata === undefined
       ? {}