@absol-labs/agent 0.10.0 → 0.12.0-rc.1

package/src/mcp/service-invoker.ts

@@ -0,0 +1,285 @@
+import {
+  RegistryUnavailableError,
+  type DiscoverServicesOptions,
+  type ServiceListing,
+} from "../discovery/registry.js";
+import {
+  invoke as defaultInvoke,
+  type InvokeStreamReader,
+} from "../sdk/invoke.js";
+import type {
+  HttpMethod,
+  InvocationCapabilityDomainInput,
+  InvocationCapabilitySigner,
+} from "../capability/invocation-capability.js";
+
+/**
+ * The "use" half of the MCP tool surface.
+ *
+ * The MCP server could open a stream and settle it but could not CALL the
+ * service the stream paid for — an agent that hired an endpoint through this
+ * server had no way to reach it, which made every other tool a payment rail
+ * with no product on the other end. This module is the same path
+ * `metrik invoke` takes (`../cli/commands/invoke.ts`): resolve the stream's
+ * VERIFIED listing, sign a single-use `InvocationCapability` as the stream's
+ * buyer, and call the operator's gateway-fronted origin.
+ *
+ * It moves no funds and signs no transaction. Billing is a function of elapsed
+ * verified time, not of calls (see {@link METERING_MODEL} in `./server.ts`), so
+ * an invocation is authorized by the stream alone and is deliberately NOT
+ * gated by the spend mandate — there is no spend to bound.
+ */
+
+/**
+ * Cap on the response body handed back to the MCP caller.
+ *
+ * An MCP tool result is pasted into a model's context. A seller can return a
+ * body of any size, and an unbounded one would blow the context (or the host's
+ * message limit) on a single call. Truncation is reported explicitly rather
+ * than silently, so an agent can tell a short answer from a clipped one.
+ */
+export const MAX_INVOCATION_RESPONSE_BYTES = 64 * 1024;
+
+/** Raised when no verified listing in the registry matches the stream's `serviceRef`. */
+export class ServiceListingNotFoundError extends Error {
+  readonly serviceRef: `0x${string}`;
+
+  constructor(serviceRef: `0x${string}`) {
+    super(`no verified listing matches serviceRef ${serviceRef}`);
+    this.name = "ServiceListingNotFoundError";
+    this.serviceRef = serviceRef;
+  }
+}
+
+export interface ServiceInvocationRequest {
+  readonly streamId: `0x${string}`;
+  readonly method: HttpMethod;
+  /** Origin-relative path, e.g. `/price?symbol=BTC`. */
+  readonly path: string;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly body?: string;
+  readonly ttlSeconds?: number;
+}
+
+export interface ServiceInvocationResult {
+  readonly streamId: `0x${string}`;
+  readonly method: HttpMethod;
+  readonly path: string;
+  readonly status: number;
+  readonly ok: boolean;
+  readonly headers: Record<string, string>;
+  readonly body: string;
+  readonly bodyTruncated: boolean;
+  /** The single-use capability this call was authorized by. */
+  readonly capability: {
+    readonly nonce: `0x${string}`;
+    readonly expiry: number;
+  };
+  readonly routing: {
+    readonly serviceRef: `0x${string}`;
+    readonly operator: `0x${string}`;
+    readonly access: "public" | "gated";
+    /** The signed origin the call went to — never an unsigned caller-supplied URL. */
+    readonly origin: string;
+  };
+  /**
+   * The caller-auth gateway's machine-readable rejection reason when it refused
+   * the capability, or `null`. Distinguishes "the seller's app returned 403"
+   * from "the gateway would not let the call through, and here is why".
+   */
+  readonly gatewayDenialReason: string | null;
+}
+
+export interface ServiceInvoker {
+  invokeService(
+    request: ServiceInvocationRequest,
+  ): Promise<ServiceInvocationResult>;
+}
+
+/** Discovery driver — same shape as the server's, kept local to avoid an import cycle. */
+type DiscoverServicesFn = (
+  opts?: DiscoverServicesOptions,
+) => Promise<ServiceListing[]>;
+
+export interface CreateServiceInvokerOptions {
+  /** Reads the stream's buyer/serviceRef/status/expiry. */
+  readonly streamReader: InvokeStreamReader;
+  /** The server's own wallet. Must BE the stream's buyer or the call fails closed. */
+  readonly buyer: InvocationCapabilitySigner;
+  /** `{chainId, verifyingContract}` of the escrow the stream settles on. */
+  readonly domain: InvocationCapabilityDomainInput;
+  readonly discoverServices: DiscoverServicesFn;
+  /** Registry read options (URL/apikey). Passed through to discovery. */
+  readonly discoverOptions?: DiscoverServicesOptions;
+  /**
+   * Clock for the capability's expiry and the stream's liveness check.
+   * Defaults to the wall clock; injectable so a test can pin it.
+   */
+  readonly now?: () => number;
+  /** Injectable for tests. Defaults to the real `invoke()`. */
+  readonly invokeImpl?: typeof defaultInvoke;
+  readonly maxResponseBytes?: number;
+}
+
+export function createServiceInvoker(
+  options: CreateServiceInvokerOptions,
+): ServiceInvoker {
+  const invokeImpl = options.invokeImpl ?? defaultInvoke;
+  const maxBytes = options.maxResponseBytes ?? MAX_INVOCATION_RESPONSE_BYTES;
+
+  return {
+    async invokeService(request) {
+      // ONE read, used twice. The listing lookup needs the stream's serviceRef
+      // and `invoke()` re-reads the stream to authorize the call; memoizing
+      // makes both decisions come from the SAME snapshot (no window where the
+      // listing is resolved from one state and the capability signed against
+      // another) and costs one RPC round trip instead of two.
+      const reader = memoizeStreamReader(options.streamReader);
+      const stream = await reader.getStreamV2(request.streamId);
+      const listing = await resolveVerifiedListing(
+        stream.serviceRef as `0x${string}`,
+        options,
+      );
+
+      const result = await invokeImpl(
+        request.streamId,
+        {
+          method: request.method,
+          path: request.path,
+          ...(request.headers === undefined
+            ? {}
+            : { headers: request.headers }),
+          ...(request.body === undefined ? {} : { body: request.body }),
+        },
+        {
+          streamReader: reader,
+          buyer: options.buyer,
+          domain: options.domain,
+          listing,
+          ...(request.ttlSeconds === undefined
+            ? {}
+            : { ttlSeconds: request.ttlSeconds }),
+          ...(options.now === undefined ? {} : { nowSeconds: options.now() }),
+        },
+      );
+
+      const raw = await result.response.text();
+      const truncated = Buffer.byteLength(raw, "utf8") > maxBytes;
+      const body = truncated
+        ? Buffer.from(raw, "utf8").subarray(0, maxBytes).toString("utf8")
+        : raw;
+
+      return {
+        streamId: request.streamId,
+        method: request.method,
+        path: request.path,
+        status: result.response.status,
+        ok: result.response.ok,
+        headers: Object.fromEntries(result.response.headers.entries()),
+        body,
+        bodyTruncated: truncated,
+        capability: {
+          nonce: result.capability.nonce as `0x${string}`,
+          expiry: result.capability.expiry,
+        },
+        routing: {
+          serviceRef: listing.serviceRef,
+          operator: listing.operator,
+          access: listing.access,
+          origin: safeOrigin(listing.accessUrl),
+        },
+        gatewayDenialReason: readGatewayDenialReason(
+          result.response.status,
+          raw,
+        ),
+      };
+    },
+  };
+}
+
+/**
+ * Finds the operator-signed listing for a `serviceRef`.
+ *
+ * The registry is an untrusted transport: `discoverServices` re-derives every
+ * `serviceRef` from the signed record and recovers the operator's signature, so
+ * a compromised registry can neither invent an operator nor redirect an
+ * invocation to an origin its operator never signed. That verification is why
+ * this tool routes through discovery instead of accepting a caller-supplied URL
+ * — an LLM-chosen base URL is exactly the injection this design refuses.
+ */
+async function resolveVerifiedListing(
+  serviceRef: `0x${string}`,
+  options: CreateServiceInvokerOptions,
+): Promise<ServiceListing> {
+  const listings = await options.discoverServices(options.discoverOptions);
+  const wanted = serviceRef.toLowerCase();
+  const match = listings.find(
+    (listing) => listing.serviceRef.toLowerCase() === wanted,
+  );
+  if (match === undefined) {
+    throw new ServiceListingNotFoundError(serviceRef);
+  }
+  return match;
+}
+
+/** Wraps a reader so repeated reads of the SAME stream id reuse one result. */
+function memoizeStreamReader(reader: InvokeStreamReader): InvokeStreamReader {
+  const cache = new Map<
+    string,
+    ReturnType<InvokeStreamReader["getStreamV2"]>
+  >();
+  return {
+    getStreamV2(streamId) {
+      const key = streamId.toLowerCase();
+      const cached = cache.get(key);
+      if (cached !== undefined) {
+        return cached;
+      }
+      const pending = reader.getStreamV2(streamId);
+      cache.set(key, pending);
+      return pending;
+    },
+  };
+}
+
+/**
+ * Extracts the caller-auth gateway's `reason` from a 402/403 body.
+ *
+ * The gateway answers a refused capability with
+ * `{"authorized":false,"reason":"<closed-set reason>"}`
+ * (`../gateway/http-server.ts`). Surfacing that verbatim turns "403" into
+ * something an agent can act on — `stream-expired` and `nonce-replayed` call
+ * for opposite responses.
+ */
+function readGatewayDenialReason(status: number, body: string): string | null {
+  if (status !== 402 && status !== 403) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(body) as {
+      readonly authorized?: unknown;
+      readonly reason?: unknown;
+    } | null;
+    if (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      parsed.authorized === false &&
+      typeof parsed.reason === "string"
+    ) {
+      return parsed.reason;
+    }
+  } catch {
+    // Not the gateway's JSON shape — a plain upstream 403. Nothing to add.
+  }
+  return null;
+}
+
+function safeOrigin(url: string): string {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return url;
+  }
+}
+
+export { RegistryUnavailableError };