@absol-labs/agent 0.4.0 → 0.5.0

package/src/index.ts

@@ -113,6 +113,21 @@ export {
   type WalletBackedAgentClient,
 } from "./wallet/provider.js";
 
+export {
+  UnsupportedFaucetChainError,
+  faucetHint,
+  getWalletBalances,
+  requestCdpFaucet,
+  type BalanceReader,
+  type CdpFaucetClientLike,
+  type FaucetHint,
+  type FaucetRequestResult,
+  type FaucetToken,
+  type GetWalletBalancesOptions,
+  type RequestCdpFaucetOptions,
+  type WalletBalances,
+} from "./wallet/lifecycle.js";
+
 export {
   ReclaimConsumerProofService,
   ResponseProofUnavailableError,
@@ -154,6 +169,72 @@ export {
   type WireDeliveryReceipt,
 } from "./zktls/t2-delivery-proof.js";
 
+export {
+  CAPABILITY_HEADER_NAME,
+  DEFAULT_CAPABILITY_TTL_SECONDS,
+  InvalidCapabilityHeaderError,
+  buildInvocationCapabilityTypedData,
+  createInvocationCapabilityEip712Domain,
+  decodeCapabilityHeader,
+  encodeCapabilityHeader,
+  generateCapabilityNonce,
+  hashInvocationPath,
+  httpMethodSchema,
+  invocationCapabilityDomainName,
+  invocationCapabilityDomainVersion,
+  invocationCapabilitySchema,
+  invocationCapabilityTypedData,
+  normalizeInvocationPath,
+  recoverInvocationCapabilitySigner,
+  signInvocationCapability,
+  signedInvocationCapabilitySchema,
+  type HttpMethod,
+  type InvocationCapability,
+  type InvocationCapabilityDomainInput,
+  type SignedInvocationCapability,
+} from "./capability/invocation-capability.js";
+
+export {
+  CallerAuthGateway,
+  InMemoryNonceReplayCache,
+  UnknownStreamGatewayError,
+  createSdkStreamReader,
+  type CallerAuthDecision,
+  type CallerAuthDenialReason,
+  type CallerAuthGatewayConfig,
+  type CallerAuthRequestInput,
+  type GatewayStreamView,
+  type NonceReplayCache,
+  type StreamReader,
+} from "./gateway/caller-auth-gateway.js";
+
+export {
+  createCallerAuthGatewayServer,
+  parseCallerAuthGatewayEnvConfig,
+  startCallerAuthGatewayServerFromEnv,
+  type CallerAuthGatewayEnvConfig,
+  type CallerAuthGatewayServer,
+  type CallerAuthGatewayServerConfig,
+} from "./gateway/http-server.js";
+
+export {
+  InvokeBuyerMismatchError,
+  InvokeStreamExpiredError,
+  InvokeStreamNotActiveError,
+  capabilityFor,
+  createSdkInvokeStreamReader,
+  invoke,
+  invokeWithT2DeliveryProof,
+  type CapabilityForOptions,
+  type InvokeOptions,
+  type InvokeResult,
+  type InvokeServiceInput,
+  type InvokeStreamReader,
+  type InvokeStreamView,
+  type InvokeWithT2DeliveryProofOptions,
+  type InvokeWithT2DeliveryProofResult,
+} from "./sdk/invoke.js";
+
 // Framework adapters are NOT re-exported from this top-level barrel on purpose.
 // Some of them (notably the Coinbase AgentKit adapter) pull heavy optional
 // dependency graphs, so importing "@absol-labs/agent" must stay light and load

package/src/mcp/server.ts

@@ -171,13 +171,13 @@ export const METRIK_MCP_TOOLS: readonly McpToolSpec[] = [
   {
     name: "check_stream_status",
     description:
-      "Read a stream's live status, accrued amount, and claimable/reclaimable balances.",
+      "Read a stream's live status, accrued amount, and claimable/reclaimable balances. In V2, failed or unproven intervals do not advance cumulative entitlement; the stream remains active until buyer close or expiry.",
     movesFunds: false,
   },
   {
     name: "reclaim_unspent",
     description:
-      "Close a stream and reclaim unspent funds to the buyer after failure or completion.",
+      "Close a stream and reclaim unspent funds to the buyer. V2 reclaim follows checkpoint finalization or escape-window rules.",
     movesFunds: true,
   },
   {

package/src/sdk/invoke.ts

@@ -0,0 +1,313 @@
+import { type DeliveryReceiptDomainInput } from "@absol-labs/shared";
+import { MetrikClient } from "@absol-labs/sdk";
+import type { Address, Hex, LocalAccount } from "viem";
+
+import {
+  buildT2DeliveryProofSubmission,
+  type BuildT2DeliveryProofResult,
+  type DeliveryProofAttestor,
+  type PaidRouteRequestSpec,
+} from "../zktls/t2-delivery-proof.js";
+import {
+  CAPABILITY_HEADER_NAME,
+  encodeCapabilityHeader,
+  generateCapabilityNonce,
+  hashInvocationPath,
+  signInvocationCapability,
+  type HttpMethod,
+  type InvocationCapability,
+  type InvocationCapabilityDomainInput,
+  type SignedInvocationCapability,
+  DEFAULT_CAPABILITY_TTL_SECONDS,
+} from "../capability/invocation-capability.js";
+
+/**
+ * Buyer half of the pay -> use loop (metrik-agent#64, impl of #62 part 2/2).
+ *
+ * After `hire()`/`openStream()`, an agent calls the purchased service directly
+ * with no out-of-band credentials: `invoke()` loads the stream, builds+signs
+ * a minimal-scope `InvocationCapability`, attaches it, and calls the
+ * gateway-fronted service (`../gateway/caller-auth-gateway.ts`).
+ */
+
+/** The subset of `MetrikClient.getStreamV2` this module needs. Duck-typed so any real SDK client satisfies it. */
+export interface InvokeStreamView {
+  readonly buyer: Address;
+  readonly operator: Address;
+  readonly serviceRef: Hex;
+  readonly status: "active" | "closed";
+  readonly expiresAt: number;
+}
+
+export interface InvokeStreamReader {
+  getStreamV2(streamId: Hex): Promise<InvokeStreamView>;
+}
+
+/** Default `InvokeStreamReader`: a real, read-only `MetrikClient` (no wallet, no writes). */
+export function createSdkInvokeStreamReader(options: {
+  readonly escrowAddress: Address;
+  readonly rpcUrl: string;
+}): InvokeStreamReader {
+  const metrik = MetrikClient.baseSepolia({
+    escrow: options.escrowAddress,
+    rpcUrl: options.rpcUrl,
+  });
+  return {
+    async getStreamV2(streamId) {
+      const stream = await metrik.getStreamV2(streamId);
+      return {
+        buyer: stream.buyer,
+        operator: stream.operator,
+        serviceRef: stream.serviceRef,
+        status: stream.status,
+        expiresAt: stream.expiresAt,
+      };
+    },
+  };
+}
+
+export class InvokeStreamNotActiveError extends Error {
+  constructor(streamId: Hex, status: string) {
+    super(`stream ${streamId} is not active (status=${status})`);
+    this.name = "InvokeStreamNotActiveError";
+  }
+}
+
+export class InvokeStreamExpiredError extends Error {
+  constructor(streamId: Hex, expiresAt: number) {
+    super(`stream ${streamId} expired at ${expiresAt}`);
+    this.name = "InvokeStreamExpiredError";
+  }
+}
+
+export class InvokeBuyerMismatchError extends Error {
+  constructor(streamId: Hex, streamBuyer: Address, signer: Address) {
+    super(
+      `stream ${streamId} buyer ${streamBuyer} does not match the signing account ${signer}`,
+    );
+    this.name = "InvokeBuyerMismatchError";
+  }
+}
+
+export interface CapabilityForOptions {
+  readonly buyer: LocalAccount;
+  readonly domain: InvocationCapabilityDomainInput;
+  readonly serviceRef: Hex;
+  /** Default {@link DEFAULT_CAPABILITY_TTL_SECONDS}. */
+  readonly ttlSeconds?: number;
+  /** Default a fresh random nonce. */
+  readonly nonce?: Hex;
+  /** Default `Math.floor(Date.now() / 1000)`. Injectable for tests. */
+  readonly nowSeconds?: number;
+}
+
+/**
+ * Builds and signs a minimal-scope `InvocationCapability` for one
+ * `method`+`path` call against `streamId`, WITHOUT touching the network.
+ */
+export async function capabilityFor(
+  streamId: Hex,
+  request: { readonly method: HttpMethod; readonly path: string },
+  options: CapabilityForOptions,
+): Promise<SignedInvocationCapability> {
+  const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+  const capability: InvocationCapability = {
+    streamId,
+    buyer: options.buyer.address,
+    serviceRef: options.serviceRef,
+    method: request.method,
+    pathHash: hashInvocationPath(request.path),
+    nonce: options.nonce ?? generateCapabilityNonce(),
+    expiry: nowSeconds + (options.ttlSeconds ?? DEFAULT_CAPABILITY_TTL_SECONDS),
+  };
+  const signature = await signInvocationCapability(
+    capability,
+    options.domain,
+    options.buyer,
+  );
+  return { ...capability, signature };
+}
+
+export interface InvokeServiceInput {
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly body?: NonNullable<RequestInit["body"]>;
+}
+
+export interface InvokeOptions {
+  /** Reads the stream's current serviceRef/operator/status/expiry. Real default: a `MetrikClient` instance. */
+  readonly streamReader: InvokeStreamReader;
+  /** The buyer's own wallet - signs the capability, never broadcasts a transaction. */
+  readonly buyer: LocalAccount;
+  /** `{chainId, verifyingContract}` - the `StreamEscrowV2` the stream settles on. */
+  readonly domain: InvocationCapabilityDomainInput;
+  /** Base URL of the gateway-fronted service (from the service listing/descriptor). */
+  readonly serviceBaseUrl: string;
+  readonly ttlSeconds?: number;
+  readonly nonce?: Hex;
+  readonly nowSeconds?: number;
+  /** Injectable `fetch` implementation, for tests. Default: global `fetch`. */
+  readonly fetchImpl?: typeof fetch;
+}
+
+export interface InvokeResult {
+  readonly response: Response;
+  readonly capability: SignedInvocationCapability;
+  readonly stream: InvokeStreamView;
+}
+
+/**
+ * `open()` -> `invoke()`: loads the stream, builds+signs a capability scoped
+ * to exactly this `method`+`path`, and calls the gateway-fronted service.
+ * Fails closed BEFORE any network call to the service if the stream is not
+ * active, is expired, or does not belong to the signing account.
+ */
+export async function invoke(
+  streamId: Hex,
+  request: InvokeServiceInput,
+  options: InvokeOptions,
+): Promise<InvokeResult> {
+  const stream = await options.streamReader.getStreamV2(streamId);
+  const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+
+  if (stream.buyer.toLowerCase() !== options.buyer.address.toLowerCase()) {
+    throw new InvokeBuyerMismatchError(
+      streamId,
+      stream.buyer,
+      options.buyer.address,
+    );
+  }
+  if (stream.status !== "active") {
+    throw new InvokeStreamNotActiveError(streamId, stream.status);
+  }
+  if (nowSeconds >= stream.expiresAt) {
+    throw new InvokeStreamExpiredError(streamId, stream.expiresAt);
+  }
+
+  const capability = await capabilityFor(streamId, request, {
+    buyer: options.buyer,
+    domain: options.domain,
+    serviceRef: stream.serviceRef,
+    ...(options.ttlSeconds === undefined
+      ? {}
+      : { ttlSeconds: options.ttlSeconds }),
+    ...(options.nonce === undefined ? {} : { nonce: options.nonce }),
+    nowSeconds,
+  });
+
+  const header = encodeCapabilityHeader(capability);
+  const url = new URL(request.path, options.serviceBaseUrl).toString();
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const response = await fetchImpl(url, {
+    method: request.method,
+    headers: {
+      ...(request.headers ?? {}),
+      [CAPABILITY_HEADER_NAME]: header,
+    },
+    ...(request.body === undefined ? {} : { body: request.body }),
+  });
+
+  return { response, capability, stream };
+}
+
+// ── T2 integration: usage + delivery proof as one action ───────────────────
+
+export interface InvokeWithT2DeliveryProofOptions {
+  readonly streamReader: InvokeStreamReader;
+  readonly buyer: LocalAccount;
+  readonly domain: DeliveryReceiptDomainInput;
+  /** The T2 paid-route spec (absolute `url`, `responseMatches`, nonce injection point, ...). */
+  readonly request: PaidRouteRequestSpec;
+  /** Which billing interval this delivery proof covers. */
+  readonly intervalIndex: bigint;
+  /** Oracle-issued anti-replay nonce, from `GET /delivery/nonce`. */
+  readonly nonce: Hex;
+  readonly issuedAt?: number;
+  readonly mandateId?: string;
+  readonly attestor?: DeliveryProofAttestor;
+  readonly capabilityTtlSeconds?: number;
+  readonly capabilityNonce?: Hex;
+  readonly nowSeconds?: number;
+}
+
+export interface InvokeWithT2DeliveryProofResult {
+  readonly capability: SignedInvocationCapability;
+  readonly stream: InvokeStreamView;
+  readonly t2: BuildT2DeliveryProofResult;
+}
+
+/**
+ * The T2 variant of `invoke()`: the SAME capability-authorized call the
+ * gateway serves is what the buyer's Reclaim attestor proves, so usage and
+ * delivery proof are one action (issue #63's "the invocation IS the
+ * delivery"). Attaches the `InvocationCapability` header to the exact request
+ * `buildT2DeliveryProofSubmission` proves via zkTLS, then signs the resulting
+ * `DeliveryReceipt` - identical evidence chain as the plain T2 flow, just
+ * capability-gated at the gateway.
+ */
+export async function invokeWithT2DeliveryProof(
+  streamId: Hex,
+  options: InvokeWithT2DeliveryProofOptions,
+): Promise<InvokeWithT2DeliveryProofResult> {
+  const stream = await options.streamReader.getStreamV2(streamId);
+  const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+
+  if (stream.buyer.toLowerCase() !== options.buyer.address.toLowerCase()) {
+    throw new InvokeBuyerMismatchError(
+      streamId,
+      stream.buyer,
+      options.buyer.address,
+    );
+  }
+  if (stream.status !== "active") {
+    throw new InvokeStreamNotActiveError(streamId, stream.status);
+  }
+  if (nowSeconds >= stream.expiresAt) {
+    throw new InvokeStreamExpiredError(streamId, stream.expiresAt);
+  }
+
+  const path = new URL(options.request.url).pathname;
+  const capability = await capabilityFor(
+    streamId,
+    { method: options.request.method ?? "GET", path },
+    {
+      buyer: options.buyer,
+      domain: options.domain,
+      serviceRef: stream.serviceRef,
+      ...(options.capabilityTtlSeconds === undefined
+        ? {}
+        : { ttlSeconds: options.capabilityTtlSeconds }),
+      ...(options.capabilityNonce === undefined
+        ? {}
+        : { nonce: options.capabilityNonce }),
+      nowSeconds,
+    },
+  );
+
+  const requestWithCapability: PaidRouteRequestSpec = {
+    ...options.request,
+    headers: {
+      ...(options.request.headers ?? {}),
+      [CAPABILITY_HEADER_NAME]: encodeCapabilityHeader(capability),
+    },
+  };
+
+  const t2 = await buildT2DeliveryProofSubmission({
+    streamId,
+    operator: stream.operator,
+    serviceRef: stream.serviceRef,
+    intervalIndex: options.intervalIndex,
+    nonce: options.nonce,
+    buyer: options.buyer,
+    domain: options.domain,
+    request: requestWithCapability,
+    ...(options.issuedAt === undefined ? {} : { issuedAt: options.issuedAt }),
+    ...(options.mandateId === undefined
+      ? {}
+      : { mandateId: options.mandateId }),
+    ...(options.attestor === undefined ? {} : { attestor: options.attestor }),
+  });
+
+  return { capability, stream, t2 };
+}

package/src/wallet/lifecycle.ts

@@ -0,0 +1,158 @@
+import { erc20Abi, type Address } from "viem";
+
+/**
+ * Agent wallet lifecycle helpers (metrik-agent#65).
+ *
+ * `../wallet/provider.ts` already resolves a wallet (injected key or a
+ * Coinbase CDP Server Wallet v2 account) and hands back a viem `Account` that
+ * can sign directly — `resolveAgentWallet()`'s CDP path is create-OR-restore
+ * by construction (`cdp.evm.getOrCreateAccount({ name })` is idempotent: the
+ * same `ownerName` always resolves to the same on-chain address, so a second
+ * run with the same env "restores" rather than creates a new wallet).
+ *
+ * This module adds the remaining thin, non-custodial lifecycle pieces the
+ * issue asks for: reading balances, a testnet faucet hint, and requesting
+ * funds from the CDP faucet. It deliberately does NOT wrap signing — a
+ * `ResolvedAgentWallet.account` is already a plain viem `Account`
+ * (`signMessage` / `signTypedData` / `signTransaction` all work as-is), and
+ * adding a second signing surface here would be exactly the "second wallet
+ * system" AGENTS.md warns against.
+ */
+
+/** Native gas balance + USDC balance for one address. */
+export interface WalletBalances {
+  /** Native token balance (ETH on Base/Base Sepolia), in wei. */
+  readonly nativeWei: bigint;
+  /** USDC balance, in atomic units (6 decimals). */
+  readonly usdcAtomic: bigint;
+}
+
+/** The subset of a viem `PublicClient` balance reads need. Duck-typed so any real client satisfies it. */
+export interface BalanceReader {
+  getBalance(args: { readonly address: Address }): Promise<bigint>;
+  readContract(args: {
+    readonly address: Address;
+    readonly abi: typeof erc20Abi;
+    readonly functionName: "balanceOf";
+    readonly args: readonly [Address];
+  }): Promise<unknown>;
+}
+
+export interface GetWalletBalancesOptions {
+  readonly publicClient: BalanceReader;
+  readonly address: Address;
+  /** The USDC token contract to read the ERC-20 balance from. */
+  readonly usdc: Address;
+}
+
+/** Reads a wallet's native gas balance and USDC balance in one call. Read-only — no signing, no writes. */
+export async function getWalletBalances(
+  options: GetWalletBalancesOptions,
+): Promise<WalletBalances> {
+  const [nativeWei, usdcAtomic] = await Promise.all([
+    options.publicClient.getBalance({ address: options.address }),
+    options.publicClient.readContract({
+      address: options.usdc,
+      abi: erc20Abi,
+      functionName: "balanceOf",
+      args: [options.address],
+    }),
+  ]);
+  return { nativeWei, usdcAtomic: usdcAtomic as bigint };
+}
+
+/** Human-facing pointers to fund a freshly created/restored testnet wallet. */
+export interface FaucetHint {
+  readonly network: string;
+  /** Coinbase CDP faucet — funds native ETH (and, on some networks, USDC) for a CDP-managed address. */
+  readonly cdpFaucetUrl: string;
+  /** Circle's own Base Sepolia USDC faucet — an alternative USDC source that doesn't require a CDP account. */
+  readonly usdcFaucetUrl: string;
+  /** How to request the same funds programmatically from a CDP wallet — see {@link requestCdpFaucet}. */
+  readonly programmaticHint: string;
+}
+
+export class UnsupportedFaucetChainError extends Error {
+  constructor(chainId: number) {
+    super(
+      `no known testnet faucet for chainId ${chainId} (Metrik is Base Sepolia (84532) only)`,
+    );
+    this.name = "UnsupportedFaucetChainError";
+  }
+}
+
+const BASE_SEPOLIA_CHAIN_ID = 84532;
+
+const BASE_SEPOLIA_FAUCET_HINT: FaucetHint = {
+  network: "base-sepolia",
+  cdpFaucetUrl: "https://portal.cdp.coinbase.com/products/faucet",
+  usdcFaucetUrl: "https://faucet.circle.com",
+  programmaticHint:
+    "requestCdpFaucet({ cdp, address, token: 'eth' | 'usdc' }) — subject to a 24h per-address rate limit",
+};
+
+/** A faucet hint for the given chain. Only Base Sepolia (84532) is supported — Metrik is testnet-only, single-chain. */
+export function faucetHint(chainId: number): FaucetHint {
+  if (chainId !== BASE_SEPOLIA_CHAIN_ID) {
+    throw new UnsupportedFaucetChainError(chainId);
+  }
+  return BASE_SEPOLIA_FAUCET_HINT;
+}
+
+export type FaucetToken = "eth" | "usdc";
+
+/** The subset of the Coinbase CDP client the faucet request needs. Duck-typed for testability. */
+export interface CdpFaucetClientLike {
+  readonly evm: {
+    requestFaucet(options: {
+      readonly address: Address;
+      readonly network: string;
+      readonly token: FaucetToken;
+    }): Promise<{ readonly transactionHash: string }>;
+  };
+}
+
+export interface RequestCdpFaucetOptions {
+  readonly cdp: CdpFaucetClientLike;
+  readonly address: Address;
+  readonly token: FaucetToken;
+  /** Default `"base-sepolia"`. */
+  readonly network?: string;
+}
+
+export interface FaucetRequestResult {
+  /** `true` iff the faucet accepted the request (a tx hash was returned). */
+  readonly requested: boolean;
+  readonly txHash?: string;
+  /**
+   * Set when `requested` is `false`. The CDP faucet enforces a 24h per-address
+   * rate limit, so a failure here is an EXPECTED, non-fatal outcome — never
+   * thrown. Callers should log this and fall back to checking whether the
+   * balance is already sufficient.
+   */
+  readonly error?: string;
+}
+
+/**
+ * Requests testnet funds from the Coinbase CDP faucet for a CDP-managed
+ * address. Tolerates the faucet's 24h rate limit and any other request
+ * failure by returning `{ requested: false, error }` — it never throws, so a
+ * caller can always fall through to reading the current balance instead.
+ */
+export async function requestCdpFaucet(
+  options: RequestCdpFaucetOptions,
+): Promise<FaucetRequestResult> {
+  try {
+    const result = await options.cdp.evm.requestFaucet({
+      address: options.address,
+      network: options.network ?? "base-sepolia",
+      token: options.token,
+    });
+    return { requested: true, txHash: result.transactionHash };
+  } catch (error) {
+    return {
+      requested: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}