@agentgrant.cash/cli 1.4.7 → 1.5.0

package/dist/cli/commands/agent.js

@@ -72,6 +72,55 @@ export function registerAgent(program) {
         });
         emit(ctx, { result: data }, () => ui.green("✓ Done."));
     });
+    program
+        .command("do-task <query>")
+        .description("Run any pay-per-use task from a plain-language request (the backend picks + pays the vendor)")
+        .option("-i, --input <json>", "structured input for the task, as JSON")
+        .option("--confirm", "confirm a spend the backend flagged as needing approval")
+        .action(async (query, opts, cmd) => {
+        const ctx = buildContext(cmd);
+        if (!ctx.agent.connected)
+            throw new NotConnectedError("agent");
+        let input;
+        if (opts.input) {
+            try {
+                input = JSON.parse(String(opts.input));
+            }
+            catch {
+                throw new Error("--input must be valid JSON.");
+            }
+        }
+        const data = await ctx.agent.doTask({
+            query,
+            ...(input !== undefined ? { input } : {}),
+            ...(opts.confirm ? { confirm: true } : {}),
+        });
+        emit(ctx, { result: data }, () => `${ui.title("Task")} ${ui.dim("(use --json for the full result)")}`);
+    });
+    program
+        .command("best-vendor <capability>")
+        .description("See the ranked vendors for a capability, top pick first (no charge)")
+        .option("--include-untested", "also surface unverified vendors, flagged untested")
+        .action(async (capability, opts, cmd) => {
+        const ctx = buildContext(cmd);
+        if (!ctx.agent.connected)
+            throw new NotConnectedError("agent");
+        const data = await ctx.agent.bestVendor({
+            capability,
+            ...(opts.includeUntested ? { includeUntested: true } : {}),
+        });
+        emit(ctx, { result: data }, () => `${ui.title("Vendors")} ${ui.dim("(use --json for the ranking)")}`);
+    });
+    program
+        .command("find-capability <query>")
+        .description("Match a plain-language request to the capabilities the agent can run (no charge)")
+        .action(async (query, _opts, cmd) => {
+        const ctx = buildContext(cmd);
+        if (!ctx.agent.connected)
+            throw new NotConnectedError("agent");
+        const data = await ctx.agent.findCapability(query);
+        emit(ctx, { result: data }, () => `${ui.title("Capabilities")} ${ui.dim("(use --json for the matches)")}`);
+    });
     program
         .command("discover <origin>")
         .alias("add")

package/dist/lib/agent-client.d.ts

@@ -5,6 +5,35 @@ export interface AgentClientOpts {
     auth?: TokenHolder;
     fetchImpl?: typeof fetch;
 }
+/**
+ * The backend's `NamedFunctionResult` (POST /do-task), returned VERBATIM. The
+ * client is a thin caller — it never re-implements selection/failover/refund;
+ * the money-safe engine owns those and encodes its outcome in `status`. A driving
+ * agent keys off `status` (`settlement_pending` = still confirming, don't re-run;
+ * `blocked` + `code` = terminal, stop). `data` shape varies by provider.
+ */
+export interface NamedFunctionResult {
+    status: "ok" | "needs_input" | "no_vendor" | "all_failed" | "settlement_pending" | "unknown_function" | "blocked";
+    [k: string]: unknown;
+}
+/** One ranked vendor for a capability (GET /agent/best-vendor). */
+export interface VendorPick {
+    slug: string;
+    name: string;
+    priceMinor: string;
+    url?: string;
+    method?: string;
+    asset?: string;
+    untested?: boolean;
+    [k: string]: unknown;
+}
+/** Ranked vendors + top pick for a capability (GET /agent/best-vendor). */
+export interface VendorSelectionResult {
+    capability: string;
+    vendors: VendorPick[];
+    best: VendorPick | null;
+    message: string;
+}
 export declare class AgentClient {
     private base;
     private auth?;
@@ -40,6 +69,19 @@ export declare class AgentClient {
     tx(id: string): Promise<Record<string, unknown>>;
     /** Exact POST /x402/pay contract for a catalog entry by slug (requestSchema + price). No spend. */
     schema(slug: string): Promise<Record<string, unknown>>;
+    /**
+     * Ranked vendors for a capability (`GET /agent/best-vendor`). Reads only — no
+     * spend. `includeUntested` opts in 'probed' vendors ranked below every verified
+     * one and flagged `untested`; omit it to route only execution-verified vendors.
+     */
+    bestVendor(b: {
+        capability: string;
+        includeUntested?: boolean;
+    }): Promise<VendorSelectionResult>;
+    /** Free-text capability match (`GET /agent/find-capability`). Reads only — no spend. */
+    findCapability(query: string): Promise<{
+        matches: unknown[];
+    }>;
     /** Ingest any x402 origin's endpoints into the catalog so they become searchable/payable. */
     discover(origin: string): Promise<Record<string, unknown>>;
     /** Claim an invite / bonus credit by code. Mints or tops up the session's spendable funds. */
@@ -50,6 +92,19 @@ export declare class AgentClient {
         code: string;
         expiresAt: number;
     }>;
+    /**
+     * One-shot natural-language task (`POST /do-task`): the backend resolves the
+     * query to the best vendor, validates input, pays under the session guardrails,
+     * and fails over — all server-side. Returns the `NamedFunctionResult` VERBATIM
+     * (including demote/refund/stop outcomes); the client never re-implements the
+     * engine. An `Idempotency-Key` guards the write path against a double-charge on
+     * retry; a transport error is tagged `recoverable` exactly like {@link fetchPay}.
+     */
+    doTask(b: {
+        query: string;
+        input?: Record<string, unknown>;
+        confirm?: boolean;
+    }): Promise<NamedFunctionResult>;
     /**
      * Pay + run an endpoint via the session. Body matches `POST /x402/pay`'s
      * schema: `method` is required (uppercased), `expectedPriceMinor` (the spend

package/dist/lib/agent-client.js

@@ -142,6 +142,22 @@ export class AgentClient {
     schema(slug) {
         return this.request("GET", `/marketplace/x402/${encodeURIComponent(slug)}`, { auth: true });
     }
+    /**
+     * Ranked vendors for a capability (`GET /agent/best-vendor`). Reads only — no
+     * spend. `includeUntested` opts in 'probed' vendors ranked below every verified
+     * one and flagged `untested`; omit it to route only execution-verified vendors.
+     */
+    bestVendor(b) {
+        const p = new URLSearchParams({ capability: b.capability });
+        if (b.includeUntested)
+            p.set("includeUntested", "true");
+        return this.request("GET", `/agent/best-vendor?${p}`, { auth: true });
+    }
+    /** Free-text capability match (`GET /agent/find-capability`). Reads only — no spend. */
+    findCapability(query) {
+        const p = new URLSearchParams({ query });
+        return this.request("GET", `/agent/find-capability?${p}`, { auth: true });
+    }
     // ── catalog + account management ──
     /** Ingest any x402 origin's endpoints into the catalog so they become searchable/payable. */
     discover(origin) {
@@ -162,6 +178,25 @@ export class AgentClient {
         return this.request("POST", "/account/link-code", { body: {}, auth: true });
     }
     // ── spends (session-owned, guardrailed) ──
+    /**
+     * One-shot natural-language task (`POST /do-task`): the backend resolves the
+     * query to the best vendor, validates input, pays under the session guardrails,
+     * and fails over — all server-side. Returns the `NamedFunctionResult` VERBATIM
+     * (including demote/refund/stop outcomes); the client never re-implements the
+     * engine. An `Idempotency-Key` guards the write path against a double-charge on
+     * retry; a transport error is tagged `recoverable` exactly like {@link fetchPay}.
+     */
+    doTask(b) {
+        return this.request("POST", "/do-task", {
+            body: {
+                query: b.query,
+                ...(b.input !== undefined ? { input: b.input } : {}),
+                ...(b.confirm !== undefined ? { confirm: b.confirm } : {}),
+            },
+            auth: true,
+            idempotent: true,
+        });
+    }
     /**
      * Pay + run an endpoint via the session. Body matches `POST /x402/pay`'s
      * schema: `method` is required (uppercased), `expectedPriceMinor` (the spend

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentgrant.cash/cli",
-  "version": "1.4.7",
+  "version": "1.5.0",
   "description": "Grant Cash — one CLI for your money (gold) and your agent (pay-per-use services). Routes to the Perfolio backend and the Agent-mode backend behind a single, plain-language surface.",
   "type": "module",
   "main": "./dist/lib/index.js",