@absol-labs/agent 0.9.1 → 0.10.0

package/src/cli/commands/discover.ts

@@ -0,0 +1,228 @@
+import { RegistryUnavailableError } from "../../discovery/registry.js";
+import { integerFlag, stringFlag } from "../args.js";
+import {
+  attesterDisclosure,
+  attesterSetUnavailableWarning,
+  operatorAttestsOwnDelivery,
+  readAttesterSet,
+  type AttesterSet,
+} from "../attesters.js";
+import { listingDetail, orderListings } from "../descriptor.js";
+import { CliError } from "../errors.js";
+import type { CommandContext, CommandSpec } from "../context.js";
+
+const TIERS = new Set([0, 1, 2]);
+
+export const discoverCommand: CommandSpec = {
+  name: "discover",
+  summary: "List cryptographically verified services in the Metrik registry",
+  usage:
+    "metrik discover [--min-tier 0|1|2] [--category NAME] [--operator 0x…] [--limit N]",
+  flags: ["min-tier", "category", "limit", "operator"],
+  signs: false,
+  async run(context: CommandContext): Promise<void> {
+    const { args, config, out, deps } = context;
+    const minTier = integerFlag(args, "min-tier");
+    if (minTier !== undefined && !TIERS.has(minTier)) {
+      throw new CliError(`--min-tier must be 0, 1 or 2 (got ${minTier})`, {
+        exitCode: 2,
+      });
+    }
+    const limit = integerFlag(args, "limit");
+    const category = stringFlag(args, "category");
+    const operator = stringFlag(args, "operator");
+
+    let result;
+    try {
+      result = await deps.discover({
+        registryUrl: config.registryUrl,
+        ...(category === undefined ? {} : { category }),
+        logger: { warn: (...parts) => out.note(parts.map(String).join(" ")) },
+      });
+    } catch (error) {
+      if (error instanceof RegistryUnavailableError) {
+        // Deliberately NOT an empty list: "the registry was unreachable" and
+        // "the marketplace is empty" are different facts and must not be
+        // rendered the same way.
+        throw new CliError(
+          `the service registry at ${config.registryUrl} could not be read`,
+          {
+            exitCode: 4,
+            hint: "this is a registry outage, not an empty marketplace — no listing was dropped by it.",
+            cause: error,
+          },
+        );
+      }
+      throw error;
+    }
+
+    let services = result.services.filter(
+      (service) => minTier === undefined || service.tier >= minTier,
+    );
+    if (operator !== undefined) {
+      const wanted = operator.toLowerCase();
+      services = services.filter(
+        (service) => service.operator.toLowerCase() === wanted,
+      );
+    }
+    // Strongest-declared-verification first, then serviceRef. The registry's own
+    // order is an implementation detail of whatever inserted the rows, so
+    // `--limit 1` used to hand a newcomer whichever listing happened to be first
+    // — including a listing that exists precisely to fail its canaries.
+    services = orderListings(services);
+    if (limit !== undefined) services = services.slice(0, limit);
+
+    // Who attests to the delivery these listings are "verified" for. `discover`
+    // advertises tiers and "cryptographically verified", so it is the command
+    // that owes the buyer the composition of the attesting set. Read soft: a
+    // registry listing is still worth printing when the escrow will not answer,
+    // and the unknown is reported as unknown.
+    const attesters: AttesterSet =
+      services.length === 0
+        ? { signers: null, unavailable: "no listing to check" }
+        : await readAttesterSet(deps.createReadClient(config));
+
+    out.result({
+      registryUrl: config.registryUrl,
+      registryAvailable: result.registryAvailable,
+      source: result.source,
+      count: services.length,
+      oracleSigners: attesters.signers,
+      oracleSignersUnavailable: attesters.unavailable,
+      services: services.map((service) => {
+        // Everything below comes from the signed record whose signature was
+        // already recovered and matched — never from an unsigned column.
+        const detail = listingDetail(service.signed);
+        return {
+          serviceRef: service.serviceRef,
+          operator: service.operator,
+          name: service.name,
+          category: service.category,
+          tier: service.tier,
+          access: service.access,
+          publicUrl: service.publicUrl,
+          accessUrl: service.accessUrl,
+          verification: service.verification,
+          authModel: detail.authModel,
+          endpoints: detail.endpoints,
+          example: detail.example,
+          rates: detail.rates,
+          // `true` = the party being paid is also one of the parties attesting
+          // to delivery. `null` = the signer set could not be read, which is
+          // UNKNOWN and must not be treated as `false`.
+          operatorIsOracleSigner: operatorAttestsOwnDelivery(
+            attesters,
+            service.operator,
+          ),
+          // The operator's own signed words. Metrik neither verifies nor
+          // enforces them — see the note printed under the listings.
+          slaClaim: detail.rates?.slaDescription ?? null,
+          slaClaimVerified: false,
+        };
+      }),
+    });
+
+    if (services.length === 0) {
+      out.print(
+        `No listings matched (registry served ${result.services.length}, filters removed the rest).`,
+      );
+      return;
+    }
+
+    out.print(
+      `${services.length} verified listing${services.length === 1 ? "" : "s"} from ${config.registryUrl}, strongest declared verification first`,
+    );
+    for (const service of services) {
+      const detail = listingDetail(service.signed);
+      out.print("");
+      out.print(`${service.name ?? "(unnamed)"}  [tier ${service.tier}]`);
+      out.table([
+        ["serviceRef", service.serviceRef],
+        ["operator", service.operator],
+        ["access", service.access],
+        ["url", service.accessUrl ?? service.publicUrl],
+        ["category", service.category ?? "-"],
+        ...(detail.rates === null
+          ? []
+          : ([
+              [
+                "rate band",
+                describeRateBand(
+                  detail.rates.minRatePerSecond,
+                  detail.rates.maxRatePerSecond,
+                ),
+              ],
+            ] as const)),
+      ]);
+      if (detail.endpoints.length > 0) {
+        out.print("  endpoints");
+        out.table(
+          detail.endpoints.map(
+            (endpoint) =>
+              [
+                `  ${endpoint.method} ${endpoint.path}`,
+                endpoint.description ?? endpoint.name,
+              ] as const,
+          ),
+        );
+      }
+      if (detail.example !== null) {
+        // The operator's own signed words about this service. It is also how a
+        // listing that exists to FAIL announces itself.
+        if (detail.example.description !== null) {
+          out.print(`  example  ${detail.example.description}`);
+        }
+        if (detail.example.request !== null) {
+          out.print(
+            `  request  ${detail.example.endpoint}  ${JSON.stringify(detail.example.request)}`,
+          );
+        }
+        if (detail.example.response !== null) {
+          out.print(`  response ${JSON.stringify(detail.example.response)}`);
+        }
+      }
+      if (detail.rates?.slaDescription != null) {
+        // Labelled at the point of display, not only in a footnote. One live
+        // listing claims "two consecutive failed intervals auto-pause the
+        // stream"; StreamEscrowV2 has no paused state at all, so that claim is
+        // false and nothing in the protocol makes it true.
+        out.print(
+          `  sla      ${detail.rates.slaDescription}  [operator's own claim - NOT verified or enforced by Metrik]`,
+        );
+      }
+      // Only an actual overlap is reported per listing. The "could not read the
+      // signer set" case is one fact about the escrow, not one per row, and is
+      // printed once below.
+      if (operatorAttestsOwnDelivery(attesters, service.operator) === true) {
+        out.note(
+          `${service.serviceRef}: ${attesterDisclosure(attesters, service.operator) ?? ""}`,
+        );
+      }
+    }
+    const setUnavailable = attesterSetUnavailableWarning(attesters);
+    if (setUnavailable !== null) out.note(setUnavailable);
+    out.print("");
+    out.print(
+      "SLA text above is the operator's own signed marketing copy. Metrik verifies DELIVERY, not any promise made about it: the escrow has no paused state, nothing auto-refunds, and no SLA string changes what accrues.",
+    );
+    out.print(
+      "Hire one:  metrik open --service <serviceRef> --rate <usdc/s> --budget <usdc> --duration <seconds>",
+    );
+    out.print(
+      "The rate band above is in USDC BASE UNITS per second — pass it with `--units atomic`.",
+    );
+  },
+};
+
+/**
+ * The operator's accepted `ratePerSecond` window, in USDC base units per second
+ * exactly as signed. Rendered as integers, never converted to decimal USDC: a
+ * band of 100-10000 base units is 0.0001-0.01 USDC, and rounding it for display
+ * is how someone opens a stream the operator will not accept.
+ */
+function describeRateBand(min: string | null, max: string | null): string {
+  if (min === null && max === null) return "not declared";
+  if (min === null) return `up to ${max} base units / second`;
+  if (max === null) return `from ${min} base units / second`;
+  return `${min} - ${max} base units / second (atomic)`;
+}

package/src/cli/commands/invoke.ts

@@ -0,0 +1,177 @@
+import {
+  httpMethodSchema,
+  type HttpMethod,
+} from "../../capability/invocation-capability.js";
+import {
+  InvokeBuyerMismatchError,
+  InvokeStreamExpiredError,
+  InvokeStreamNotActiveError,
+} from "../../sdk/invoke.js";
+import { integerFlag, stringFlag, stringFlags } from "../args.js";
+import { assertTestnetRpc, parseBytes32 } from "../config.js";
+import { CliError, usageError } from "../errors.js";
+import { resolveListing } from "../listings.js";
+import { resolveCliWallet } from "../wallet.js";
+import type { CommandContext, CommandSpec } from "../context.js";
+
+export const invokeCommand: CommandSpec = {
+  name: "invoke",
+  summary:
+    "Call the service you are paying for, authorized by the stream itself",
+  usage:
+    'metrik invoke <streamId> [--path / (default)] [--method GET] [--body \'{"text":"hi"}\'] [--header "K: V"] [--ttl 60 (default)] [--base-url URL]',
+  flags: ["path", "method", "body", "header", "ttl", "base-url"],
+  // Broadcasts nothing. It DOES need the key: the invocation capability is an
+  // off-chain EIP-712 signature by the stream's buyer.
+  signs: false,
+  requiresKey: true,
+  async run(context: CommandContext): Promise<void> {
+    const { args, config, env, out, deps } = context;
+    const [streamIdArg] = args.positionals;
+    if (streamIdArg === undefined) {
+      throw usageError("metrik invoke requires a <streamId>");
+    }
+    const streamId = parseBytes32(streamIdArg, "<streamId>");
+    const path = stringFlag(args, "path") ?? "/";
+    if (!path.startsWith("/") || path.startsWith("//")) {
+      throw usageError(
+        `--path must be origin-relative and start with a single slash (got "${path}")`,
+      );
+    }
+    const methodResult = httpMethodSchema.safeParse(
+      (stringFlag(args, "method") ?? "GET").toUpperCase(),
+    );
+    if (!methodResult.success) {
+      throw usageError(
+        `--method must be one of the HTTP methods a capability can authorize (got "${stringFlag(args, "method")}")`,
+      );
+    }
+    const method: HttpMethod = methodResult.data;
+    const body = stringFlag(args, "body");
+    // Lifetime of the signed capability. Left unset, the capability signer's own
+    // default applies (see `DEFAULT_CAPABILITY_TTL_SECONDS`).
+    const ttlSeconds = integerFlag(args, "ttl");
+    const baseUrlOverride = stringFlag(args, "base-url");
+
+    const headers = parseHeaders(stringFlags(args, "header"));
+    if (body !== undefined && !hasHeader(headers, "content-type")) {
+      headers["content-type"] = "application/json";
+    }
+
+    const { account } = await resolveCliWallet(env, {
+      purpose: "capability",
+      note: out.note,
+    });
+    const read = deps.createReadClient(config);
+    // No transaction is signed here — but the capability is bound to
+    // {chainId, escrow}, so a wrong-chain RPC would mint a capability the
+    // gateway can never accept. Fail before the network call, not after.
+    await assertTestnetRpc(config, () => read.getChainId());
+
+    const stream = await read.getStreamV2(streamId);
+    const listing =
+      baseUrlOverride === undefined
+        ? await resolveListing(context, stream.serviceRef, { required: true })
+        : null;
+    if (baseUrlOverride !== undefined) {
+      out.note(
+        "warning: --base-url bypasses verified listing routing; the origin is not signature-checked.",
+      );
+    }
+
+    let result;
+    try {
+      result = await deps.invoke(
+        streamId,
+        {
+          method,
+          path,
+          headers,
+          ...(body === undefined ? {} : { body }),
+        },
+        {
+          streamReader: deps.createInvokeStreamReader(config),
+          buyer: account,
+          domain: { chainId: config.chainId, verifyingContract: config.escrow },
+          ...(listing === null ? {} : { listing }),
+          ...(baseUrlOverride === undefined
+            ? {}
+            : { serviceBaseUrl: baseUrlOverride }),
+          ...(ttlSeconds === undefined ? {} : { ttlSeconds }),
+          nowSeconds: deps.nowSeconds(),
+        },
+      );
+    } catch (error) {
+      throw explainInvokeFailure(error, account.address);
+    }
+
+    const responseBody = await result.response.text();
+    out.result({
+      streamId,
+      method,
+      path,
+      status: result.response.status,
+      ok: result.response.ok,
+      capabilityNonce: result.capability.nonce,
+      capabilityExpiry: result.capability.expiry,
+      headers: Object.fromEntries(result.response.headers.entries()),
+      body: responseBody,
+    });
+    out.print(`${method} ${path} -> ${result.response.status}`);
+    out.print("");
+    out.print(responseBody);
+
+    if (!result.response.ok) {
+      throw new CliError(`the service returned ${result.response.status}`, {
+        exitCode: 4,
+      });
+    }
+  },
+};
+
+function explainInvokeFailure(error: unknown, signer: string): unknown {
+  if (error instanceof InvokeBuyerMismatchError) {
+    return new CliError(
+      "this stream does not belong to the configured wallet",
+      {
+        exitCode: 3,
+        hint: `the capability is signed by ${signer}; only the stream's buyer can invoke it.`,
+        cause: error,
+      },
+    );
+  }
+  if (error instanceof InvokeStreamNotActiveError) {
+    return new CliError("the stream is closed, so it authorizes nothing", {
+      exitCode: 4,
+      cause: error,
+    });
+  }
+  if (error instanceof InvokeStreamExpiredError) {
+    return new CliError("the stream has expired, so it authorizes nothing", {
+      exitCode: 4,
+      hint: "reclaim the unspent budget with `metrik reclaim <streamId>`.",
+      cause: error,
+    });
+  }
+  return error;
+}
+
+function parseHeaders(raw: readonly string[]): Record<string, string> {
+  const headers: Record<string, string> = {};
+  for (const entry of raw) {
+    const separator = entry.indexOf(":");
+    if (separator <= 0) {
+      throw usageError(`--header must be "Name: value" (got "${entry}")`);
+    }
+    headers[entry.slice(0, separator).trim().toLowerCase()] = entry
+      .slice(separator + 1)
+      .trim();
+  }
+  return headers;
+}
+
+function hasHeader(headers: Record<string, string>, name: string): boolean {
+  return Object.keys(headers).some(
+    (key) => key.toLowerCase() === name.toLowerCase(),
+  );
+}

package/src/cli/commands/mcp.ts

@@ -0,0 +1,135 @@
+import { booleanFlag, stringFlag } from "../args.js";
+import { packageVersion } from "../version.js";
+import { CDP_ENV_VARS, PRIVATE_KEY_ENV } from "../wallet.js";
+import type { CommandContext, CommandSpec } from "../context.js";
+
+/** The published executable an MCP host starts. Declared in `package.json#bin`. */
+const MCP_BIN = "metrik-mcp";
+const PACKAGE_NAME = "@absol-labs/agent";
+
+/** Default key under `mcpServers`. Overridable so two wallets can coexist. */
+const DEFAULT_SERVER_NAME = "metrik";
+
+/**
+ * Every `METRIK_AGENT_MANDATE_*` variable the MCP server requires, with the
+ * placeholder emitted when the current environment does not set it.
+ *
+ * The server refuses to start without all four (`ServerMandateConfigError`):
+ * there is no implicit unbounded mandate, and a printed config that omitted
+ * them would be a config that fails closed on first launch — which is the
+ * failure this command exists to prevent.
+ */
+const MANDATE_VARS: readonly (readonly [string, string])[] = [
+  [
+    "METRIK_AGENT_MANDATE_MAX_PER_STREAM_USDC",
+    "<max USDC base units per stream>",
+  ],
+  ["METRIK_AGENT_MANDATE_MAX_TOTAL_USDC", "<max USDC base units in total>"],
+  [
+    "METRIK_AGENT_MANDATE_MAX_RATE_PER_SECOND_USDC",
+    "<max USDC base units per second>",
+  ],
+  [
+    "METRIK_AGENT_MANDATE_MAX_DURATION_SECONDS",
+    "<max stream duration in seconds>",
+  ],
+];
+
+export const mcpCommand: CommandSpec = {
+  name: "mcp",
+  summary: "Print the MCP client config that runs this package's MCP server",
+  usage: "metrik mcp [--print-config] [--name metrik]",
+  flags: ["print-config", "name"],
+  signs: false,
+  async run(context: CommandContext): Promise<void> {
+    const { args, config, env, out } = context;
+    // A bare `metrik mcp` used to fail with exit 2 demanding --print-config,
+    // while the top-level help said this command "prints the MCP client
+    // config". Refusing to do the one thing the command advertises taught a
+    // reviewer that the tool was broken. It now does it — and says plainly, on
+    // stderr, that it printed a config rather than starting a server, which is
+    // the confusion the refusal was guarding against.
+    if (!booleanFlag(args, "print-config")) {
+      out.note(
+        "metrik mcp printed the MCP CLIENT CONFIG below; it did NOT start a server. The server is the separate `metrik-mcp` executable, which your MCP host launches. The explicit form of this command is `metrik mcp --print-config`.",
+      );
+    }
+    const name = stringFlag(args, "name") ?? DEFAULT_SERVER_NAME;
+
+    // Pinned to THIS version. `npx --package @absol-labs/agent metrik-mcp`
+    // would silently follow `latest` on every host restart, which is not what
+    // an MCP host that signs spend mandates should do.
+    const version = packageVersion();
+
+    const document = {
+      mcpServers: {
+        [name]: {
+          command: "npx",
+          args: ["-y", "--package", `${PACKAGE_NAME}@${version}`, MCP_BIN],
+          env: {
+            // The MCP server has NO defaults for these three — it fails closed
+            // when any is missing. They are filled from this CLI's resolved
+            // settlement config, so the printed block matches the deployment
+            // the CLI is already pointed at.
+            METRIK_AGENT_CHAIN_ID: String(config.chainId),
+            METRIK_AGENT_RPC_URL: config.rpcUrl,
+            METRIK_AGENT_ESCROW: config.escrow,
+            METRIK_AGENT_USDC: config.usdc,
+            ...walletEnv(env),
+            ...mandateEnv(env),
+          },
+        },
+      },
+    };
+
+    out.result(document);
+    out.print(
+      `Paste this into your MCP client's config (Claude Desktop: claude_desktop_config.json), then replace every <…> placeholder:`,
+    );
+    out.print("");
+    out.print(JSON.stringify(document, null, 2));
+    out.print("");
+    out.print(
+      `The host runs \`npx -y --package ${PACKAGE_NAME}@${version} ${MCP_BIN}\` — the published executable, pinned to this version. Nothing in this repository is referenced.`,
+    );
+    out.print(
+      "Secrets are placeholders by design: this command never reads a key out of your environment and prints it back.",
+    );
+  },
+};
+
+/**
+ * Wallet variables, shaped to match how the environment running this command is
+ * already configured — CDP if that is what is set, a raw key otherwise.
+ *
+ * Values are ALWAYS placeholders. `metrik` prints derived addresses and never
+ * echoes a credential, and a config block is the single most likely thing to be
+ * pasted into a chat window or an issue.
+ */
+function walletEnv(env: NodeJS.ProcessEnv): Record<string, string> {
+  const usesCdp =
+    env[PRIVATE_KEY_ENV] === undefined &&
+    CDP_ENV_VARS.some((variable) => (env[variable] ?? "").length > 0);
+  if (usesCdp) {
+    return Object.fromEntries(
+      CDP_ENV_VARS.map((variable) => [variable, `<your ${variable}>`]),
+    );
+  }
+  return {
+    [PRIVATE_KEY_ENV]: "<0x… a funded Base Sepolia test key>",
+  };
+}
+
+/**
+ * Mandate ceilings. These are policy, not secrets, so a configured value is
+ * carried through verbatim — the point is a block that starts the server, and
+ * re-typing four caps from memory is where a wrong ceiling comes from.
+ */
+function mandateEnv(env: NodeJS.ProcessEnv): Record<string, string> {
+  return Object.fromEntries(
+    MANDATE_VARS.map(([variable, placeholder]) => [
+      variable,
+      env[variable] ?? placeholder,
+    ]),
+  );
+}