Merge pull request #1013 from boboliu-1010/fix/x402-terminal-output

fix(cli): correct payment preflight, pagination and text output

Author: gummy789j

ts/src/adapters/inbound/cli/arity/index.ts

@@ -134,6 +134,7 @@ function applyArity(y: Argv, fields: ZodObject<ZodRawShape>): Argv {
   for (const f of introspectFields(fields)) {
     y.option(f.kebab, {
       type: f.baseType === "boolean" ? "boolean" : "string",
+      ...(f.kebab === "body-file" ? { nargs: 1 } : {}),
       ...(f.isArray ? { array: true } : {}), // repeatable flag → yargs collects into an array
       describe: f.description,
       demandOption: false, // requiredness is enforced by zod, not yargs

ts/src/adapters/inbound/cli/commands/bai.ts

@@ -1,3 +1,4 @@
+import { baiRechargeText, baiUsageText, baiRecordsText, baiOrdersText } from "../render/bai.js";
 import {
   assertBaiRechargeMinimum,
   baiRechargeAmount,
@@ -57,10 +58,12 @@ const rechargeFields = z.object({
 
 export const baiRechargeSpec: ChainSpec = {
   path: ["bai", "recharge"],
+  formatText: baiRechargeText,
   network: "optional",
   wallet: "optional",
   auth: "conditional",
   broadcasts: true,
+  supportsWait: false,
   capability: "bai.recharge",
   requires,
   positionals: [{ field: "amount" }],
@@ -141,6 +144,7 @@ export function registerBaiCommands(registry: CommandRegistry, service: BaiServi
   });
   registry.add({
     path: ["bai", "report-recharge"],
+    formatText: baiRechargeText,
     network: "none",
     wallet: "none",
     auth: "none",
@@ -170,12 +174,19 @@ export function registerBaiCommands(registry: CommandRegistry, service: BaiServi
     examples: [
       { cmd: "wallet-cli bai report-recharge 0x" + "a".repeat(64) + " --chain base --amount 1" },
     ],
-    run: async (_ctx, _network, input) => service.rechargeReport(input),
+    run: async (ctx, _network, input) => {
+      ctx.emit({
+        type: "activity",
+        message: "Submitting the existing transaction hash to B.AI; no new payment will be sent…",
+      });
+      return service.rechargeReport(input);
+    },
   } satisfies CommandDefinition);
 
   const empty = z.object({});
   registry.add({
     path: ["bai", "usage-summary"],
+    formatText: baiUsageText,
     network: "none",
     wallet: "none",
     auth: "none",
@@ -186,7 +197,10 @@ export function registerBaiCommands(registry: CommandRegistry, service: BaiServi
     fields: empty,
     input: empty,
     examples: [{ cmd: "wallet-cli bai usage-summary" }],
-    run: async () => service.usage(),
+    run: async (ctx) => {
+      ctx.emit({ type: "activity", message: "Fetching B.AI credit balance and usage summary…" });
+      return service.usage();
+    },
   } satisfies CommandDefinition);
 
   const usageListFields = listFields.extend({
@@ -199,6 +213,7 @@ export function registerBaiCommands(registry: CommandRegistry, service: BaiServi
   });
   registry.add({
     path: ["bai", "usage-records"],
+    formatText: baiRecordsText,
     network: "none",
     wallet: "none",
     auth: "none",
@@ -207,11 +222,15 @@ export function registerBaiCommands(registry: CommandRegistry, service: BaiServi
     fields: usageListFields,
     input: usageListFields,
     examples: [{ cmd: "wallet-cli bai usage-records --limit 20" }],
-    run: async (_context, _network, input) => service.usageList(input),
+    run: async (ctx, _network, input) => {
+      ctx.emit({ type: "activity", message: "Fetching B.AI usage records…" });
+      return service.usageList(input);
+    },
   } satisfies CommandDefinition);
 
   registry.add({
     path: ["bai", "recharge-orders"],
+    formatText: baiOrdersText,
     network: "none",
     wallet: "none",
     auth: "none",
@@ -221,6 +240,7 @@ export function registerBaiCommands(registry: CommandRegistry, service: BaiServi
     input: listFields,
     examples: [{ cmd: "wallet-cli bai recharge-orders --limit 20" }],
     run: async (context, _network, input) => {
+      context.emit({ type: "activity", message: "Fetching B.AI recharge orders…" });
       const { warnings, ...result } = await service.rechargeList(input);
       for (const warning of warnings ?? []) context.warn(warning);
       return result;

ts/src/adapters/inbound/cli/commands/erc8004.ts

@@ -1,10 +1,10 @@
-import { agentShowText } from "../render/x402.js";
+import { agentShowText, operatorCheckText } from "../render/x402.js";
 import { z } from "zod";
 import type { ChainSpec, FamilyBinding } from "../contracts/index.js";
 import type { AgentService } from "../../../../application/use-cases/agent-service.js";
 import { Schemas, addressFamilyFieldsFor } from "../schemas/index.js";
 import { governanceTxRefine, tronTxModeFields, txModeFields } from "./shared.js";
-import { TextFormatters, renderGenericText } from "../render/index.js";
+import { TextFormatters } from "../render/index.js";
 
 const agentId = z
   .string()
@@ -152,7 +152,7 @@ export const operatorCheckSpec: ChainSpec = {
   wallet: "none",
   auth: "none",
   capability: "erc8004.identity.read",
-  formatText: (data, ctx) => renderGenericText(ctx.command, ctx.net, data),
+  formatText: operatorCheckText,
   positionals: [{ field: "owner" }, { field: "operator" }],
   summary: "Check an owner-wide Agent operator approval",
   baseFields: z.object({
@@ -181,8 +181,8 @@ export function showEvmBinding(service: AgentService): FamilyBinding {
   return binding(
     "evm",
     async (ctx, net, input) => {
-      const result = await service.show(net, input.id);
-      for (const warning of result.warnings ?? []) ctx.warn(warning);
+      const { warnings, ...result } = await service.show(net, input.id);
+      for (const warning of warnings ?? []) ctx.warn(warning);
       return result;
     },
     [],
@@ -193,8 +193,8 @@ export function showTronBinding(service: AgentService): FamilyBinding {
   return binding(
     "tron",
     async (ctx, net, input) => {
-      const result = await service.show(net, input.id);
-      for (const warning of result.warnings ?? []) ctx.warn(warning);
+      const { warnings, ...result } = await service.show(net, input.id);
+      for (const warning of warnings ?? []) ctx.warn(warning);
       return result;
     },
     [],

ts/src/adapters/inbound/cli/commands/wallet.ts

@@ -599,6 +599,8 @@ export function registerWalletCommands(
     examples: [{ cmd: "wallet-cli delete old --yes" }],
     formatText: TextFormatters.walletDelete,
     run: async (ctx, _net, input) => {
+      const deletionWarning = wallets.deletionWarning(input.account);
+      if (deletionWarning) ctx.warn(deletionWarning);
       if (!input.yes) {
         if (!ctx.prompt.isTTY()) {
           throw new UsageError(

ts/src/adapters/inbound/cli/commands/x402.test.ts

@@ -87,3 +87,13 @@ describe("x402 command surface", () => {
     ).toBe(false);
   });
 });
+
+it("does not advertise unsupported provider type or facilitator waiting", () => {
+  const registry = new CommandRegistry();
+  registerX402Commands(registry, service());
+  expect(registry.resolveNeutral(["x402", "provider-list"])!.fields.shape).not.toHaveProperty(
+    "type",
+  );
+  for (const command of ["pay", "roundtrip"])
+    expect(registry.resolveNeutral(["x402", command])!.supportsWait).toBe(false);
+});

ts/src/adapters/inbound/cli/commands/x402.ts

@@ -1,5 +1,8 @@
 import {
   paymentText,
+  roundtripText,
+  catalogUpdateText,
+  serveText,
   providerListText,
   providerShowText,
   providerEndpointsText,
@@ -89,6 +92,7 @@ const payCommand: CommandDefinition = {
   wallet: "optional",
   auth: "conditional",
   broadcasts: true,
+  supportsWait: false,
   capability: "x402.pay",
   positionals: [{ field: "url" }],
   summary: "Request an endpoint and pay an x402 challenge",
@@ -115,12 +119,24 @@ const payCommand: CommandDefinition = {
 };
 
 const listFields = z.object({
-  limit: integerLiteral(1, 200).default(20),
-  offset: integerLiteral(0, Number.MAX_SAFE_INTEGER).default(0),
-  type: z.string().trim().min(1).optional(),
-  category: z.string().trim().min(1).optional(),
-  capability: z.string().trim().min(1).optional(),
-  network: z.string().trim().min(1).optional().describe("CAIP-2 network id"),
+  limit: integerLiteral(1, 200).default(20).describe("maximum providers to return"),
+  offset: integerLiteral(0, Number.MAX_SAFE_INTEGER)
+    .default(0)
+    .describe("zero-based pagination offset"),
+
+  category: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("filter by a category exposed by the provider catalog"),
+  capability: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("filter by a featured tag exposed by the provider catalog"),
+  network: z.string().trim().min(1).optional().describe("network alias or CAIP-2 network id"),
   includeBlocked: z.boolean().default(false).describe("include providers marked as blocked"),
 });
 
@@ -178,7 +194,8 @@ const roundtripFields = serveFields.omit({ host: true, resourceUrl: true, daemon
 const roundtripInput = roundtripFields
   .superRefine(serveRefinement)
   .refine((value) => !(value.maxGasfreeFee !== undefined && value.maxGasfreeFeeRaw !== undefined), {
-    message: "GasFree fee limits are mutually exclusive",
+    path: ["maxGasfreeFee"],
+    message: "cannot be combined with --max-gasfree-fee-raw",
     params: { errorCode: "invalid_option" },
   });
 
@@ -212,6 +229,7 @@ export function registerX402Commands(registry: CommandRegistry, service: X402Ser
 
   registry.add({
     path: ["x402", "serve"],
+    formatText: serveText,
     network: "optional",
     wallet: "none",
     auth: "none",
@@ -225,16 +243,21 @@ export function registerX402Commands(registry: CommandRegistry, service: X402Ser
     ],
     run: async (_ctx, network, input) => {
       if (!network) throw new Error("x402 serve requires a resolved network");
-      return service.serve(network, input);
+      return service.serve(network, {
+        ...input,
+        ...(_ctx.output === "text" ? { accessLog: "text" as const } : {}),
+      });
     },
   } satisfies CommandDefinition);
 
   registry.add({
     path: ["x402", "roundtrip"],
+    formatText: roundtripText,
     network: "optional",
     wallet: "optional",
     auth: "conditional",
     broadcasts: true,
+    supportsWait: false,
     capability: "x402.pay",
     summary: "Start a local paywall, pay it, and exit",
     fields: roundtripFields,
@@ -257,7 +280,7 @@ export function registerX402Commands(registry: CommandRegistry, service: X402Ser
     input: listFields,
     examples: [
       { cmd: "wallet-cli x402 provider-list" },
-      { cmd: "wallet-cli x402 provider-list --network tron:728126428 --capability recharge" },
+      { cmd: "wallet-cli x402 provider-list --network tron:728126428" },
     ],
     run: async (_ctx, _network, input) => providerResult(_ctx, service.providerList(input)),
   } satisfies CommandDefinition);
@@ -281,14 +304,15 @@ export function registerX402Commands(registry: CommandRegistry, service: X402Ser
       summary,
       fields,
       input: fields,
-      examples: [{ cmd: `wallet-cli x402 ${verb} bai/recharge` }],
+      examples: [{ cmd: `wallet-cli x402 ${verb} defillama` }],
       run: async (_ctx, _network, input) => providerResult(_ctx, run(input.provider)),
     } satisfies CommandDefinition);
   }
 
   const empty = z.object({});
   registry.add({
     path: ["x402", "update-catalog"],
+    formatText: catalogUpdateText,
     network: "none",
     wallet: "none",
     auth: "none",
@@ -337,6 +361,7 @@ async function providerResult(
   ctx: Parameters<CommandDefinition["run"]>[0],
   pending: Promise<Record<string, unknown>>,
 ) {
+  ctx.emit({ type: "activity", message: "Loading provider catalog data…" });
   const { warnings, ...data } = await pending;
   if (Array.isArray(warnings))
     for (const warning of warnings) if (typeof warning === "string") ctx.warn(warning);

ts/src/adapters/inbound/cli/contracts/command.ts

@@ -58,6 +58,8 @@ interface CommandDefinitionBase<I, O> {
   auth: AuthRequirement;
   /** broadcasts a transaction on-chain (✍️); enables the --wait global flag in help projection. */
   broadcasts?: boolean;
+  /** Override waiting support for payments submitted by an external facilitator. */
+  supportsWait?: boolean;
   /** opt-in interactive master-password handling: "establish" = set on first wallet else verify; "verify" = require existing. Commands without this keep the lazy hasMasterPassword guard. */
   passwordMode?: "establish" | "verify";
   /** expose one or more `fields` entries as leading positionals (`block [<number>]`, `use [<account>]`,
@@ -140,6 +142,8 @@ export interface ChainSpec<_I = any, O = any> {
   wallet: WalletRequirement;
   auth: AuthRequirement;
   broadcasts?: boolean;
+  /** Override waiting support for payments submitted by an external facilitator. */
+  supportsWait?: boolean;
   capability?: string;
   stdin?: StdinChannel;
   /** the stdin channel belongs to ONE family (e.g. `--tx-stdin` carries TRON's transaction JSON).
@@ -179,6 +183,7 @@ export type CommandExecutionSpec = Pick<
   | "wallet"
   | "auth"
   | "broadcasts"
+  | "supportsWait"
   | "capability"
   | "interactive"
   | "passwordMode"

ts/src/adapters/inbound/cli/contracts/envelope.ts

@@ -22,6 +22,8 @@ export interface Pagination {
   offset: number;
   limit: number | null;
   total: number | null;
+  hasMore?: boolean;
+  nextCursor?: string | null;
 }
 export interface Meta {
   durationMs: number;

ts/src/adapters/inbound/cli/help/index.ts

@@ -294,6 +294,7 @@ export class HelpService {
       auth: cmd.auth,
       wallet: cmd.wallet,
       broadcasts: cmd.broadcasts,
+      supportsWait: cmd.supportsWait,
       fields: introspectFields(cmd.fields),
       inputFlags: inputFlagsFor(cmd),
       exclusive: cmd.exclusive,
@@ -316,6 +317,7 @@ export class HelpService {
       auth: spec.auth,
       wallet: spec.wallet,
       broadcasts: spec.broadcasts,
+      supportsWait: spec.supportsWait,
       fields: introspectFields(mergedFields(def)),
       fieldFamilies: fieldFamilies(def),
       inputFlags: spec.stdin ? inputFlagsFor(spec) : [],
@@ -337,6 +339,7 @@ export class HelpService {
     auth: CommandDefinition["auth"];
     wallet: CommandDefinition["wallet"];
     broadcasts?: boolean;
+    supportsWait?: boolean;
     fields: FieldInfo[];
     /** family-specific flags, so each can be marked with the family it belongs to. */
     fieldFamilies?: Map<string, ChainFamily>;
@@ -471,7 +474,7 @@ export class HelpService {
       c.network,
       c.auth,
       c.wallet,
-      c.broadcasts ?? false,
+      c.supportsWait ?? c.broadcasts ?? false,
       c.secretsTtyOnly ?? false,
     ))
       lines.push(globalFlagLine(g));

ts/src/adapters/inbound/cli/input/secret/index.ts

@@ -197,6 +197,11 @@ export class SecretResolver implements ISecretResolver {
     }
     this.#stdinUsedBy = kind;
     if (!this.#byPath.has("-")) {
+      if (kind === "apiKey" && process.stdin.isTTY)
+        this.streams.diagnostic(
+          "info",
+          "Reading API key from stdin; finish input with Ctrl-D. Use a pipe for non-interactive input.",
+        );
       this.#byPath.set("-", this.streams.readStdinOnce().replace(/\r?\n$/, ""));
     }
     return this.#byPath.get("-")!;