@absol-labs/agent 0.4.0 → 0.6.0

package/dist/sdk/invoke.d.ts

@@ -0,0 +1,136 @@
+import { type DeliveryReceiptDomainInput } from "@absol-labs/shared";
+import type { Address, Hex, LocalAccount } from "viem";
+import type { ServiceListing } from "../discovery/registry.js";
+import { type BuildT2DeliveryProofResult, type DeliveryProofAttestor, type PaidRouteRequestSpec } from "../zktls/t2-delivery-proof.js";
+import { type HttpMethod, type InvocationCapabilityDomainInput, type SignedInvocationCapability } 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 declare function createSdkInvokeStreamReader(options: {
+    readonly escrowAddress: Address;
+    readonly rpcUrl: string;
+}): InvokeStreamReader;
+export declare class InvokeStreamNotActiveError extends Error {
+    constructor(streamId: Hex, status: string);
+}
+export declare class InvokeStreamExpiredError extends Error {
+    constructor(streamId: Hex, expiresAt: number);
+}
+export declare class InvokeBuyerMismatchError extends Error {
+    constructor(streamId: Hex, streamBuyer: Address, signer: Address);
+}
+export declare class InvokeServiceRefMismatchError extends Error {
+    constructor(streamRef: Hex, listingRef: Hex);
+}
+export declare class InvokeAccessUrlError extends Error {
+    constructor(message: string);
+}
+export declare class InvokePathError extends Error {
+    constructor(path: string);
+}
+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 declare function capabilityFor(streamId: Hex, request: {
+    readonly method: HttpMethod;
+    readonly path: string;
+}, options: CapabilityForOptions): Promise<SignedInvocationCapability>;
+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;
+    /** Preferred: a cryptographically verified result from discoverServices(). */
+    readonly listing?: ServiceListing;
+    /** @deprecated Manual escape hatch. Verified listing routing is safer. */
+    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 declare function invoke(streamId: Hex, request: InvokeServiceInput, options: InvokeOptions): Promise<InvokeResult>;
+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;
+    /** Verified listing. Gated T2 is rejected until proof-target pinning supports it. */
+    readonly listing?: ServiceListing;
+    /** 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 declare function invokeWithT2DeliveryProof(streamId: Hex, options: InvokeWithT2DeliveryProofOptions): Promise<InvokeWithT2DeliveryProofResult>;
+//# sourceMappingURL=invoke.d.ts.map

package/dist/sdk/invoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../src/sdk/invoke.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,0BAA0B,EAChC,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,EAEL,KAAK,0BAA0B,EAC/B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAC1B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAML,KAAK,UAAU,EAEf,KAAK,+BAA+B,EACpC,KAAK,0BAA0B,EAEhC,MAAM,wCAAwC,CAAC;AAEhD;;;;;;;GAOG;AAEH,kHAAkH;AAClH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACvD;AAED,6FAA6F;AAC7F,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACnD,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,kBAAkB,CAiBrB;AAED,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM;CAI1C;AAED,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,QAAQ,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM;CAI7C;AAED,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,QAAQ,EAAE,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO;CAMjE;AAED,qBAAa,6BAA8B,SAAQ,KAAK;gBAC1C,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG;CAM5C;AAED,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,IAAI,EAAE,MAAM;CAMzB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,+BAA+B,CAAC;IACjD,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC;IACzB,sDAAsD;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,oCAAoC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC;IACrB,qEAAqE;IACrE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,GAAG,EACb,OAAO,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAC/D,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,0BAA0B,CAAC,CAiBrC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,aAAa;IAC5B,6GAA6G;IAC7G,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAC1C,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,+BAA+B,CAAC;IACjD,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC;IACrB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,0BAA0B,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAsB,MAAM,CAC1B,QAAQ,EAAE,GAAG,EACb,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,YAAY,CAAC,CAmDvB;AAID,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;IACvC,qFAAqF;IACrF,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,yDAAyD;IACzD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC;IACpB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IAC1C,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,eAAe,CAAC,EAAE,GAAG,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,UAAU,EAAE,0BAA0B,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,EAAE,EAAE,0BAA0B,CAAC;CACzC;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,GAAG,EACb,OAAO,EAAE,gCAAgC,GACxC,OAAO,CAAC,+BAA+B,CAAC,CA6E1C"}

package/dist/sdk/invoke.js

@@ -0,0 +1,274 @@
+import { deriveServiceRef, recoverServiceBindingSigner, recoverServiceDescriptorSigner, signedServiceBindingSchema, signedServiceDescriptorSchema, } from "@absol-labs/shared";
+import { MetrikClient } from "@absol-labs/sdk";
+import { buildT2DeliveryProofSubmission, } from "../zktls/t2-delivery-proof.js";
+import { CAPABILITY_HEADER_NAME, encodeCapabilityHeader, generateCapabilityNonce, hashInvocationPath, signInvocationCapability, DEFAULT_CAPABILITY_TTL_SECONDS, } from "../capability/invocation-capability.js";
+/** Default `InvokeStreamReader`: a real, read-only `MetrikClient` (no wallet, no writes). */
+export function createSdkInvokeStreamReader(options) {
+    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, status) {
+        super(`stream ${streamId} is not active (status=${status})`);
+        this.name = "InvokeStreamNotActiveError";
+    }
+}
+export class InvokeStreamExpiredError extends Error {
+    constructor(streamId, expiresAt) {
+        super(`stream ${streamId} expired at ${expiresAt}`);
+        this.name = "InvokeStreamExpiredError";
+    }
+}
+export class InvokeBuyerMismatchError extends Error {
+    constructor(streamId, streamBuyer, signer) {
+        super(`stream ${streamId} buyer ${streamBuyer} does not match the signing account ${signer}`);
+        this.name = "InvokeBuyerMismatchError";
+    }
+}
+export class InvokeServiceRefMismatchError extends Error {
+    constructor(streamRef, listingRef) {
+        super(`stream serviceRef ${streamRef} does not match listing serviceRef ${listingRef}`);
+        this.name = "InvokeServiceRefMismatchError";
+    }
+}
+export class InvokeAccessUrlError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvokeAccessUrlError";
+    }
+}
+export class InvokePathError extends Error {
+    constructor(path) {
+        super(`invocation path must be origin-relative and start with one slash: ${path}`);
+        this.name = "InvokePathError";
+    }
+}
+/**
+ * Builds and signs a minimal-scope `InvocationCapability` for one
+ * `method`+`path` call against `streamId`, WITHOUT touching the network.
+ */
+export async function capabilityFor(streamId, request, options) {
+    const nowSeconds = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+    const capability = {
+        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 };
+}
+/**
+ * `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, request, options) {
+    assertOriginRelativePath(request.path);
+    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 serviceBaseUrl = await resolveInvocationBaseUrl(stream.serviceRef, options);
+    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, ensureTrailingSlash(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 };
+}
+/**
+ * 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, options) {
+    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);
+    }
+    if (options.listing !== undefined) {
+        const route = await verifyListingRoute(stream.serviceRef, options.listing);
+        if (route.access === "gated") {
+            throw new InvokeAccessUrlError("consumer-attested T2 invocation is not supported for gated listings");
+        }
+        const requestOrigin = new URL(options.request.url).origin;
+        const signedOrigin = new URL(route.url).origin;
+        if (requestOrigin !== signedOrigin) {
+            throw new InvokeAccessUrlError(`T2 request origin ${requestOrigin} does not match signed listing origin ${signedOrigin}`);
+        }
+    }
+    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 = {
+        ...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 };
+}
+async function resolveInvocationBaseUrl(streamRef, options) {
+    if (options.listing !== undefined) {
+        return (await verifyListingRoute(streamRef, options.listing)).url;
+    }
+    if (options.serviceBaseUrl === undefined) {
+        throw new InvokeAccessUrlError("a verified listing is required (or pass deprecated serviceBaseUrl explicitly)");
+    }
+    return requireHttpUrl(options.serviceBaseUrl, "serviceBaseUrl");
+}
+async function verifyListingRoute(streamRef, listing) {
+    if (streamRef.toLowerCase() !== listing.serviceRef.toLowerCase()) {
+        throw new InvokeServiceRefMismatchError(streamRef, listing.serviceRef);
+    }
+    const descriptor = signedServiceDescriptorSchema.safeParse(listing.signed);
+    if (descriptor.success) {
+        const signed = descriptor.data;
+        const derived = deriveServiceRef(signed.descriptor);
+        const signer = await recoverServiceDescriptorSigner(signed.descriptor, signed.signature);
+        const access = signed.descriptor.access ?? "public";
+        const url = access === "gated"
+            ? signed.descriptor.callerAuth?.accessUrl
+            : (signed.descriptor.interface?.baseUrl ?? signed.descriptor.publicUrl);
+        if (derived.toLowerCase() !== listing.serviceRef.toLowerCase() ||
+            signed.serviceRef.toLowerCase() !== listing.serviceRef.toLowerCase() ||
+            signer === null ||
+            signer.toLowerCase() !== signed.descriptor.operator.toLowerCase() ||
+            listing.operator.toLowerCase() !==
+                signed.descriptor.operator.toLowerCase() ||
+            listing.publicUrl !== signed.descriptor.publicUrl ||
+            listing.access !== access ||
+            url === undefined ||
+            listing.accessUrl !== url) {
+            throw new InvokeAccessUrlError("listing does not match its verified signed descriptor");
+        }
+        const verifiedUrl = requireHttpUrl(url, "signed listing access URL");
+        if (access === "gated" && new URL(verifiedUrl).protocol !== "https:") {
+            throw new InvokeAccessUrlError("signed gated listing access URL must use HTTPS");
+        }
+        return { access, url: verifiedUrl };
+    }
+    const binding = signedServiceBindingSchema.safeParse(listing.signed);
+    if (binding.success) {
+        const signed = binding.data;
+        const derived = deriveServiceRef(signed.binding);
+        const signer = await recoverServiceBindingSigner(signed.binding, signed.signature);
+        if (derived.toLowerCase() !== listing.serviceRef.toLowerCase() ||
+            signed.serviceRef.toLowerCase() !== listing.serviceRef.toLowerCase() ||
+            signer === null ||
+            signer.toLowerCase() !== signed.binding.operator.toLowerCase() ||
+            listing.operator.toLowerCase() !==
+                signed.binding.operator.toLowerCase() ||
+            listing.publicUrl !== signed.binding.publicUrl ||
+            listing.access !== "public" ||
+            listing.accessUrl !== signed.binding.publicUrl) {
+            throw new InvokeAccessUrlError("listing does not match its verified signed binding");
+        }
+        return {
+            access: "public",
+            url: requireHttpUrl(signed.binding.publicUrl, "signed listing access URL"),
+        };
+    }
+    throw new InvokeAccessUrlError("listing signed record is invalid");
+}
+function requireHttpUrl(value, label) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new InvokeAccessUrlError(`${label} must be an absolute HTTP(S) URL`);
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new InvokeAccessUrlError(`${label} must be an absolute HTTP(S) URL`);
+    }
+    return parsed.toString();
+}
+function assertOriginRelativePath(path) {
+    if (!path.startsWith("/") || path.startsWith("//") || path.includes("#")) {
+        throw new InvokePathError(path);
+    }
+}
+function ensureTrailingSlash(value) {
+    return value.endsWith("/") ? value : `${value}/`;
+}
+//# sourceMappingURL=invoke.js.map

package/dist/sdk/invoke.js.map

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

package/dist/wallet/lifecycle.d.ts

@@ -0,0 +1,101 @@
+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 declare function getWalletBalances(options: GetWalletBalancesOptions): Promise<WalletBalances>;
+/** 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 declare class UnsupportedFaucetChainError extends Error {
+    constructor(chainId: number);
+}
+/** A faucet hint for the given chain. Only Base Sepolia (84532) is supported — Metrik is testnet-only, single-chain. */
+export declare function faucetHint(chainId: number): FaucetHint;
+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 declare function requestCdpFaucet(options: RequestCdpFaucetOptions): Promise<FaucetRequestResult>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/wallet/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/wallet/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AAE9C;;;;;;;;;;;;;;;;;GAiBG;AAEH,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,0GAA0G;AAC1G,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjE,YAAY,CAAC,IAAI,EAAE;QACjB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,GAAG,EAAE,OAAO,QAAQ,CAAC;QAC9B,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC;QACnC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC;KACnC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,2GAA2G;AAC3G,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,cAAc,CAAC,CAWzB;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sGAAsG;IACtG,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6GAA6G;IAC7G,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,uGAAuG;IACvG,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,EAAE,MAAM;CAM5B;AAYD,wHAAwH;AACxH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAKtD;AAED,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,CAAC;AAEzC,kGAAkG;AAClG,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE;QACZ,aAAa,CAAC,OAAO,EAAE;YACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;YAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;YACzB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;SAC7B,GAAG,OAAO,CAAC;YAAE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACnD,CAAC;CACH;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,GAAG,EAAE,mBAAmB,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,gCAAgC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAc9B"}

package/dist/wallet/lifecycle.js

@@ -0,0 +1,57 @@
+import { erc20Abi } from "viem";
+/** Reads a wallet's native gas balance and USDC balance in one call. Read-only — no signing, no writes. */
+export async function getWalletBalances(options) {
+    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 };
+}
+export class UnsupportedFaucetChainError extends Error {
+    constructor(chainId) {
+        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 = {
+    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) {
+    if (chainId !== BASE_SEPOLIA_CHAIN_ID) {
+        throw new UnsupportedFaucetChainError(chainId);
+    }
+    return BASE_SEPOLIA_FAUCET_HINT;
+}
+/**
+ * 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) {
+    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),
+        };
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/wallet/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/wallet/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAgB,MAAM,MAAM,CAAC;AA+C9C,2GAA2G;AAC3G,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAiC;IAEjC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAChD,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;QAC7D,OAAO,CAAC,YAAY,CAAC,YAAY,CAAC;YAChC,OAAO,EAAE,OAAO,CAAC,IAAI;YACrB,GAAG,EAAE,QAAQ;YACb,YAAY,EAAE,WAAW;YACzB,IAAI,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC;SACxB,CAAC;KACH,CAAC,CAAC;IACH,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,UAAoB,EAAE,CAAC;AACzD,CAAC;AAaD,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IACpD,YAAY,OAAe;QACzB,KAAK,CACH,uCAAuC,OAAO,wCAAwC,CACvF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AAED,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAEpC,MAAM,wBAAwB,GAAe;IAC3C,OAAO,EAAE,cAAc;IACvB,YAAY,EAAE,iDAAiD;IAC/D,aAAa,EAAE,2BAA2B;IAC1C,gBAAgB,EACd,qGAAqG;CACxG,CAAC;AAEF,wHAAwH;AACxH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,IAAI,OAAO,KAAK,qBAAqB,EAAE,CAAC;QACtC,MAAM,IAAI,2BAA2B,CAAC,OAAO,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,wBAAwB,CAAC;AAClC,CAAC;AAoCD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAgC;IAEhC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC;YACjD,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,cAAc;YAC1C,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC,CAAC;QACH,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,eAAe,EAAE,CAAC;IAC7D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,SAAS,EAAE,KAAK;YAChB,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absol-labs/agent",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Metrik agent layer: x402 verified-streaming payments, an MCP server, framework tools, and spend mandates so AI agents can hire and pay verified services safely.",
   "license": "MIT",
   "author": "Absol Labs",
@@ -66,8 +66,8 @@
     "pnpm": "9.15.x"
   },
   "dependencies": {
-    "@absol-labs/sdk": "^0.4.0",
-    "@absol-labs/shared": "^0.11.0",
+    "@absol-labs/sdk": "^0.7.0",
+    "@absol-labs/shared": "^0.12.1",
     "@coinbase/cdp-sdk": "^1.51.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@reclaimprotocol/js-sdk": "^5.6.0",
@@ -108,9 +108,12 @@
     "build:e2e": "tsc -p tsconfig.e2e.build.json",
     "mcp:stdio": "tsx src/mcp/stdio.ts",
     "mcp:http": "tsx src/mcp/http-server.ts",
+    "gateway": "tsx src/gateway/server-entry.ts",
     "e2e:cdp": "node dist-e2e/scripts/e2e-cdp.js",
+    "e2e:hire": "tsx scripts/e2e-hire.ts",
     "l2:proof": "node scripts/l2-proof.mjs",
     "test": "vitest run",
+    "test:package": "node scripts/test-packed-package.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "typecheck:e2e": "tsc -p tsconfig.e2e.json --noEmit",
     "lint": "tsc -p tsconfig.json --noEmit",