@absol-labs/agent 0.9.1 → 0.10.0

package/src/cli/deps.ts

@@ -0,0 +1,437 @@
+import { streamEscrowV2Abi } from "@absol-labs/shared";
+import {
+  MetrikClient,
+  type CheckpointProof,
+  type HireComputeInput,
+  type HireComputeResult,
+  type HireTxPreview,
+  type StreamV2,
+  type StreamProofTransactionResult,
+} from "@absol-labs/sdk";
+import { erc20Abi, getAbiItem, http, type LocalAccount } from "viem";
+
+import {
+  discoverServicesDetailed,
+  type DiscoverResult,
+  type DiscoverServicesOptions,
+  type ServiceListing,
+} from "../discovery/registry.js";
+import {
+  invoke as sdkInvoke,
+  type InvokeOptions,
+  type InvokeResult,
+  type InvokeServiceInput,
+  type InvokeStreamReader,
+} from "../sdk/invoke.js";
+import {
+  VerifiedStreamAgentClient,
+  type MandateAuthorizedStreamActionInput,
+  type OpenVerifiedStreamInput,
+  type ReclaimAuthorizedStreamInput,
+  type ReclaimVerifiedStreamResult,
+} from "../sdk/client.js";
+
+import type { CliConfig } from "./config.js";
+import { RPC_RETRY_COUNT, RPC_TIMEOUT_MS, withReadTimeout } from "./timeout.js";
+
+/**
+ * Everything the CLI touches that is not pure computation, behind one
+ * injectable surface. Commands are written against these interfaces so the test
+ * suite exercises the real argument parsing, config resolution, testnet guard,
+ * retry logic and rendering against doubles — without a key, an RPC, or a
+ * single transaction.
+ */
+export interface CliReadClient {
+  /** The chain id the RPC endpoint actually serves (half of the testnet guard). */
+  getChainId(): Promise<number>;
+  getStreamV2(streamId: `0x${string}`): Promise<StreamV2>;
+  /**
+   * The ONLY live reading of accrual. `StreamEscrowV2.getStream` reports
+   * `claimedCumulative = 0` and `settledCumulative = 0` for a stream's entire
+   * active life — `settledCumulative` is written by `reclaim`, not by accrual —
+   * so a status command that reads a stream field would always print zero. The
+   * oracle's checkpoint proof carries the real earned-so-far figure.
+   */
+  checkpointProof(streamId: `0x${string}`): Promise<CheckpointProof>;
+  claimableForV2(
+    streamId: `0x${string}`,
+    cumulativeAmount: bigint,
+  ): Promise<bigint>;
+  reclaimableForV2(
+    streamId: `0x${string}`,
+    cumulativeAmount: bigint,
+  ): Promise<bigint>;
+  /** Live protocol fee, read from the escrow rather than hardcoded. */
+  protocolFeeBps(): Promise<number>;
+  /**
+   * `StreamEscrowV2.escapeGraceSeconds` (public immutable). The buyer's no-proof
+   * escape hatch unlocks at `expiresAt + escapeGraceSeconds`, so this is half of
+   * every readiness answer the CLI gives about it.
+   */
+  escapeGraceSeconds(): Promise<number>;
+  /**
+   * `StreamEscrowV2.latestCheckpointCheckedAt` — how far the oracle has
+   * published. A buyer reading "the last checkpoint is two hours old" is reading
+   * the reason their proof-based reclaim is blocked.
+   */
+  latestCheckpointCheckedAt(): Promise<number>;
+  /**
+   * `StreamEscrowV2.getOracleSigners` — every address whose signature can carry
+   * a checkpoint into the escrow.
+   *
+   * Read so the CLI can say who attests. A buyer told a listing is
+   * "cryptographically verified" is entitled to know whether the operator they
+   * are about to pay is ALSO one of the parties attesting that the delivery
+   * happened; on the live deployment that overlap exists. Disclosure only — the
+   * CLI does not refuse such a listing, it names the fact.
+   */
+  oracleSigners(): Promise<readonly `0x${string}`[]>;
+  /**
+   * The timestamp of the latest block. The escape hatch is gated on
+   * `block.timestamp`, not on the caller's clock, so readiness is answered
+   * against the chain rather than against a laptop that may be skewed.
+   */
+  latestBlockTimestamp(): Promise<number>;
+  /**
+   * Native balance of an address, in wei. Read before a fund-moving command so
+   * an unfunded wallet is reported as an unfunded wallet, rather than as the
+   * raw node error `gas required exceeds allowance (0)`.
+   */
+  nativeBalance(address: `0x${string}`): Promise<bigint>;
+  /**
+   * USDC balance of an address, in base units. Gas and deposit are SEPARATE
+   * balances, so `assertCanPayGas` passing says nothing about whether the hire
+   * can be funded — see `assertCanFundStream`.
+   */
+  usdcBalance(address: `0x${string}`): Promise<bigint>;
+  /** Current chain head, the upper bound of every log scan. */
+  blockNumber(): Promise<bigint>;
+  /**
+   * `StreamOpened` logs for one indexed party over one inclusive block window.
+   *
+   * `buyer` and `operator` are INDEXED on the event, so `role` becomes an
+   * `eth_getLogs` topic filter the NODE evaluates: the response carries only
+   * that wallet's streams regardless of how wide the window is. What bounds a
+   * window is the endpoint's per-call BLOCK RANGE cap, not the response size —
+   * see `./scan-range.ts`.
+   */
+  streamOpenedLogs(query: StreamOpenedQuery): Promise<readonly OpenedStream[]>;
+  /**
+   * Count of ANY escrow log in a single block. Used as a known-answer retention
+   * canary: a node that has pruned its log index answers a range it no longer
+   * retains with a SUCCESSFUL EMPTY result, so an empty scan is only honest
+   * from an endpoint that demonstrably still serves the oldest block in range.
+   */
+  escrowLogCountAt(block: bigint): Promise<number>;
+}
+
+/** One indexed party filter over one inclusive block window. */
+export interface StreamOpenedQuery {
+  readonly role: "buyer" | "operator";
+  readonly address: `0x${string}`;
+  readonly fromBlock: bigint;
+  readonly toBlock: bigint;
+}
+
+/** The immutable facts `StreamOpened` carries, which later state cannot restate. */
+export interface OpenedStream {
+  readonly streamId: `0x${string}`;
+  readonly buyer: `0x${string}`;
+  readonly operator: `0x${string}`;
+  readonly serviceRef: `0x${string}`;
+  /**
+   * The amount originally escrowed. V2 MUTATES `Stream.deposit` on reclaim, so
+   * the event is the only place the opening figure survives.
+   */
+  readonly deposit: bigint;
+  readonly ratePerSecond: bigint;
+  readonly expiresAt: number;
+  readonly blockNumber: bigint;
+}
+
+export interface CliWriteClient {
+  /** Build + best-effort simulate the hire WITHOUT broadcasting (`--dry-run`). */
+  buildHireTx(input: HireComputeInput): Promise<HireTxPreview>;
+  openVerifiedStream(
+    input: OpenVerifiedStreamInput,
+  ): Promise<HireComputeResult>;
+  closeStream(
+    input: MandateAuthorizedStreamActionInput,
+  ): Promise<StreamProofTransactionResult>;
+  reclaimStream(
+    input: ReclaimAuthorizedStreamInput,
+  ): Promise<ReclaimVerifiedStreamResult>;
+  /**
+   * The no-proof escape hatch. Separate from {@link reclaimStream} because it is
+   * a different transaction with a different outcome, not a mode of the same one
+   * — see `VerifiedStreamAgentClient.reclaimUnverifiedStream`.
+   */
+  reclaimUnverifiedStream(
+    input: MandateAuthorizedStreamActionInput,
+  ): Promise<StreamProofTransactionResult>;
+  /** Operator-only: redeem the verified-earned balance for a stream. */
+  claimStream(
+    input: MandateAuthorizedStreamActionInput,
+  ): Promise<StreamProofTransactionResult>;
+}
+
+export interface CliDependencies {
+  readonly createReadClient: (config: CliConfig) => CliReadClient;
+  /**
+   * `account` is nullable because `open --dry-run` broadcasts nothing and must
+   * work for someone who has no key yet. Without one the SDK still builds the
+   * calldata and simply reports that the allowance read and simulation were
+   * skipped; every fund-moving method throws rather than inventing a signer.
+   */
+  readonly createWriteClient: (
+    config: CliConfig,
+    account: LocalAccount | null,
+  ) => CliWriteClient;
+  readonly discover: (
+    options: DiscoverServicesOptions,
+  ) => Promise<DiscoverResult>;
+  readonly invoke: (
+    streamId: `0x${string}`,
+    request: InvokeServiceInput,
+    options: InvokeOptions,
+  ) => Promise<InvokeResult>;
+  readonly createInvokeStreamReader: (config: CliConfig) => InvokeStreamReader;
+  readonly nowSeconds: () => number;
+  readonly sleep: (ms: number) => Promise<void>;
+}
+
+/**
+ * The `StreamOpened` ABI entry, resolved once. Taken from the shared V2 ABI
+ * rather than re-declared: a hand-written copy that drifted by one indexed
+ * argument would silently match nothing.
+ */
+const STREAM_OPENED_EVENT = getAbiItem({
+  abi: streamEscrowV2Abi,
+  name: "StreamOpened",
+});
+
+/**
+ * The RPC transport, with an explicit per-call budget.
+ *
+ * viem's defaults leave a single `eth_call` able to hang for a long time behind
+ * three backing-off retries, which is how a `status` run reached two minutes
+ * with nothing on screen. Bounding it here bounds every read and every
+ * simulation the SDK performs, in one place.
+ */
+function rpcTransport(config: CliConfig) {
+  return http(config.rpcUrl, {
+    timeout: RPC_TIMEOUT_MS,
+    retryCount: RPC_RETRY_COUNT,
+  });
+}
+
+/** Shared `MetrikClient` construction: one escrow, declared as V2 on both keys. */
+function createMetrikClient(
+  config: CliConfig,
+  account?: LocalAccount,
+): MetrikClient {
+  return new MetrikClient({
+    chain: config.chain,
+    transport: rpcTransport(config),
+    escrow: config.escrow,
+    // Declared on BOTH keys: without `escrowV2` the SDK routes reads and
+    // settlement through the legacy V1 ABI, which reverts against
+    // StreamEscrowV2 (its one-argument views were replaced by proof-carrying
+    // ones, and `reclaim` becomes `reclaimWithProof`).
+    escrowV2: config.escrow,
+    usdc: config.usdc,
+    oracleBaseUrl: config.oracleBaseUrl,
+    settlementTarget: { chainId: config.chainId, escrow: config.escrow },
+    ...(account === undefined ? {} : { account }),
+  });
+}
+
+export const defaultCliDependencies: CliDependencies = {
+  createReadClient(config) {
+    const metrik = createMetrikClient(config);
+    return {
+      async getChainId() {
+        return await metrik.publicClient.getChainId();
+      },
+      async getStreamV2(streamId) {
+        return await metrik.getStreamV2(streamId);
+      },
+      async checkpointProof(streamId) {
+        // Not an RPC call: this is an HTTP fetch against the oracle, so the
+        // transport budget above does not cover it.
+        return await withReadTimeout(
+          async () => await metrik.checkpointProof(streamId),
+          `the oracle at ${config.oracleBaseUrl}`,
+        );
+      },
+      async claimableForV2(streamId, cumulativeAmount) {
+        return await metrik.claimableForV2(streamId, cumulativeAmount);
+      },
+      async reclaimableForV2(streamId, cumulativeAmount) {
+        return await metrik.reclaimableForV2(streamId, cumulativeAmount);
+      },
+      async nativeBalance(address) {
+        return await metrik.publicClient.getBalance({ address });
+      },
+      async usdcBalance(address) {
+        return await metrik.publicClient.readContract({
+          address: config.usdc,
+          abi: erc20Abi,
+          functionName: "balanceOf",
+          args: [address],
+        });
+      },
+      async blockNumber() {
+        return await metrik.publicClient.getBlockNumber();
+      },
+      async streamOpenedLogs({ role, address, fromBlock, toBlock }) {
+        const logs = await metrik.publicClient.getLogs({
+          address: config.escrow,
+          event: STREAM_OPENED_EVENT,
+          args: { [role]: address },
+          fromBlock,
+          toBlock,
+        });
+        // Returned as-is: the topic filter is evaluated by the node, so
+        // re-checking `log.args.buyer === address` here would imply the filter
+        // is decorative and would hide a mis-built filter behind a second pass.
+        // A wrong filter should produce a visibly wrong result, not a quietly
+        // correct one.
+        return logs.flatMap((log) =>
+          log.args.streamId === undefined ||
+          log.args.buyer === undefined ||
+          log.args.operator === undefined ||
+          log.args.serviceRef === undefined ||
+          log.args.deposit === undefined ||
+          log.args.ratePerSecond === undefined ||
+          log.args.expiresAt === undefined
+            ? []
+            : [
+                {
+                  streamId: log.args.streamId,
+                  buyer: log.args.buyer,
+                  operator: log.args.operator,
+                  serviceRef: log.args.serviceRef,
+                  deposit: log.args.deposit,
+                  ratePerSecond: log.args.ratePerSecond,
+                  expiresAt: Number(log.args.expiresAt),
+                  blockNumber: log.blockNumber ?? 0n,
+                },
+              ],
+        );
+      },
+      async escrowLogCountAt(block) {
+        const logs = await metrik.publicClient.getLogs({
+          address: config.escrow,
+          fromBlock: block,
+          toBlock: block,
+        });
+        return logs.length;
+      },
+      async protocolFeeBps() {
+        const bps = await metrik.publicClient.readContract({
+          address: config.escrow,
+          abi: streamEscrowV2Abi,
+          functionName: "protocolFeeBps",
+        });
+        return Number(bps);
+      },
+      async escapeGraceSeconds() {
+        const seconds = await metrik.publicClient.readContract({
+          address: config.escrow,
+          abi: streamEscrowV2Abi,
+          functionName: "escapeGraceSeconds",
+        });
+        return Number(seconds);
+      },
+      async latestCheckpointCheckedAt() {
+        const checkedAt = await metrik.publicClient.readContract({
+          address: config.escrow,
+          abi: streamEscrowV2Abi,
+          functionName: "latestCheckpointCheckedAt",
+        });
+        return Number(checkedAt);
+      },
+      async latestBlockTimestamp() {
+        const block = await metrik.publicClient.getBlock();
+        return Number(block.timestamp);
+      },
+      async oracleSigners() {
+        return await metrik.publicClient.readContract({
+          address: config.escrow,
+          abi: streamEscrowV2Abi,
+          functionName: "getOracleSigners",
+        });
+      },
+    };
+  },
+  createWriteClient(config, account) {
+    const clientConfig = {
+      chain: config.chain,
+      transport: rpcTransport(config),
+      escrow: config.escrow,
+      escrowV2: config.escrow,
+      usdc: config.usdc,
+      oracleBaseUrl: config.oracleBaseUrl,
+      settlementTarget: { chainId: config.chainId, escrow: config.escrow },
+      ...(account === null ? {} : { account }),
+    };
+    // The mandate-gated agent client owns every fund-moving call; the raw SDK
+    // client is used only for the build-only `--dry-run` preview, which
+    // broadcasts nothing.
+    const agentClient = new VerifiedStreamAgentClient(clientConfig);
+    const metrik = createMetrikClient(
+      config,
+      ...(account === null ? [] : ([account] as const)),
+    );
+    return {
+      async buildHireTx(input) {
+        return await metrik.buildHireTx(input);
+      },
+      async openVerifiedStream(input) {
+        return await agentClient.openVerifiedStream(input);
+      },
+      async closeStream(input) {
+        return await agentClient.closeStream(input);
+      },
+      async reclaimStream(input) {
+        return await agentClient.reclaimStream(input);
+      },
+      async reclaimUnverifiedStream(input) {
+        return await agentClient.reclaimUnverifiedStream(input);
+      },
+      async claimStream(input) {
+        return await agentClient.claimStream(input);
+      },
+    };
+  },
+  async discover(options) {
+    return await discoverServicesDetailed(options);
+  },
+  async invoke(streamId, request, options) {
+    return await sdkInvoke(streamId, request, options);
+  },
+  createInvokeStreamReader(config) {
+    const metrik = createMetrikClient(config);
+    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,
+        };
+      },
+    };
+  },
+  nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+  },
+  async sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+  },
+};
+
+export type { DiscoverResult, ServiceListing };

package/src/cli/descriptor.ts

@@ -0,0 +1,133 @@
+import type {
+  SignedServiceBinding,
+  SignedServiceDescriptor,
+} from "@absol-labs/shared";
+
+import type { DiscoveredService } from "../discovery/registry.js";
+
+/**
+ * What a listing's SIGNED descriptor already tells a newcomer — surfaced rather
+ * than discarded.
+ *
+ * The registry's signed records carry the callable endpoints, one worked example
+ * call, and the operator's accepted rate band. `metrik discover` used to project
+ * them away, so the CLI could show a `serviceRef` but never what the service
+ * DOES, what path to call, or what `--rate` the operator will accept. Everything
+ * here is read from the record whose signature was already recovered and
+ * matched, so nothing unsigned is ever presented as fact.
+ */
+export interface ListingEndpoint {
+  readonly name: string;
+  readonly path: string;
+  readonly method: string;
+  readonly description: string | null;
+}
+
+export interface ListingExample {
+  readonly endpoint: string;
+  readonly description: string | null;
+  readonly request: unknown;
+  readonly response: unknown;
+}
+
+export interface ListingRates {
+  /** USDC base units per second, as signed (decimal strings, never floats). */
+  readonly minRatePerSecond: string | null;
+  readonly maxRatePerSecond: string | null;
+  readonly currency: string | null;
+  readonly slaDescription: string | null;
+  readonly refundPolicy: string | null;
+}
+
+export interface ListingDetail {
+  readonly endpoints: readonly ListingEndpoint[];
+  readonly example: ListingExample | null;
+  readonly rates: ListingRates | null;
+  readonly authModel: string | null;
+}
+
+const EMPTY_DETAIL: ListingDetail = {
+  endpoints: [],
+  example: null,
+  rates: null,
+  authModel: null,
+};
+
+/**
+ * Project the signed record onto the presentable detail. A legacy binding (which
+ * carries no interface at all) yields empty detail rather than an invented one.
+ */
+export function listingDetail(
+  signed: SignedServiceBinding | SignedServiceDescriptor | undefined,
+): ListingDetail {
+  const descriptor = (signed as SignedServiceDescriptor | undefined)
+    ?.descriptor;
+  if (descriptor === undefined) return EMPTY_DETAIL;
+
+  const iface = descriptor.interface;
+  const commercial = descriptor.commercial;
+  return {
+    endpoints: (iface?.endpoints ?? []).map((endpoint) => ({
+      name: endpoint.name,
+      path: endpoint.path,
+      method: endpoint.method,
+      description: endpoint.description ?? null,
+    })),
+    example:
+      iface?.example === undefined
+        ? null
+        : {
+            endpoint: iface.example.endpoint,
+            description: iface.example.description ?? null,
+            request: iface.example.request ?? null,
+            response: iface.example.response ?? null,
+          },
+    rates:
+      commercial === undefined
+        ? null
+        : {
+            minRatePerSecond: commercial.minRatePerSecond ?? null,
+            maxRatePerSecond: commercial.maxRatePerSecond ?? null,
+            currency: commercial.currency ?? null,
+            slaDescription: commercial.slaDescription ?? null,
+            refundPolicy: commercial.refundPolicy ?? null,
+          },
+    authModel: iface?.authModel ?? null,
+  };
+}
+
+/**
+ * How much verification a listing actually declares. Used to order `discover`
+ * strongest-first so `--limit 1` returns the best-attested listing rather than
+ * whatever the registry happened to serve first — which is how a newcomer's very
+ * first result ended up being a deliberately-failing test fixture.
+ *
+ * This ranks the DECLARED verification spec, which is the only thing the signed
+ * record can tell us. It is a presentation order, not a trust score.
+ */
+export function verificationStrength(service: DiscoveredService): number {
+  const summary = service.verification;
+  if (summary === null) return 0;
+  return (
+    (summary.hasReexec ? 8 : 0) +
+    (summary.hasSchema ? 4 : 0) +
+    (summary.hasSla ? 2 : 0) +
+    Math.min(summary.canaries, 1)
+  );
+}
+
+/**
+ * Deterministic, strongest-verification-first order. Ties break on `serviceRef`
+ * so the same registry always renders in the same order and `--limit N` is
+ * reproducible between runs.
+ */
+export function orderListings<T extends DiscoveredService>(
+  services: readonly T[],
+): T[] {
+  return [...services].sort((left, right) => {
+    if (left.tier !== right.tier) return right.tier - left.tier;
+    const strength = verificationStrength(right) - verificationStrength(left);
+    if (strength !== 0) return strength;
+    return left.serviceRef.localeCompare(right.serviceRef);
+  });
+}