@justhandledlabs/agent-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JustHandled Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# JustHandled Agent Client
+
+A guarded CLI, JavaScript client, and local MCP server for the [JustHandled Agent Utility Gateway](https://justhandled-agent-gateway.netlify.app). The package exposes ten deterministic preflights. Each paid call costs exactly $0.05 USDC on Base mainnet and returns a versioned evidence receipt.
+
+The client fails closed before signing. It accepts only the pinned JustHandled gateway, Base mainnet, the canonical Base USDC contract, a 50,000-base-unit price, and the published merchant receiver. Customer inputs are not persisted by the gateway.
+
+## Inspect without a wallet
+
+```bash
+npx --package @justhandledlabs/agent-client justhandled-agent catalog
+npx --package @justhandledlabs/agent-client justhandled-agent preview filename-portability-preflight --json '{"paths":["CON.txt"]}'
+```
+
+Preview performs an unpaid request and validates the returned x402 terms. It does not sign or spend.
+
+## Execute one paid utility
+
+Use a dedicated low-balance Base wallet. Never provide a primary wallet key.
+
+```bash
+export JH_EVM_PRIVATE_KEY=0x...
+npx --package @justhandledlabs/agent-client justhandled-agent call filename-portability-preflight --json '{"paths":["CON.txt"]}'
+```
+
+PowerShell:
+
+```powershell
+$env:JH_EVM_PRIVATE_KEY = "0x..."
+npx.cmd --package @justhandledlabs/agent-client justhandled-agent call filename-portability-preflight --json '{"paths":["CON.txt"]}'
+```
+
+## MCP configuration
+
+```json
+{
+  "mcpServers": {
+    "justhandled": {
+      "command": "npx",
+      "args": ["-y", "@justhandledlabs/agent-client"],
+      "env": {
+        "JH_EVM_PRIVATE_KEY": "0xDEDICATED_LOW_BALANCE_WALLET_KEY"
+      }
+    }
+  }
+}
+```
+
+The MCP server exposes a free catalog tool plus one paid tool per gateway utility. Missing wallet configuration produces an error instead of a payment attempt.
+
+## Security model
+
+- Price, chain, asset, receiver, and gateway origin are pinned in code.
+- Every execution starts with an unpaid 402 preview.
+- A mismatched term aborts before signing.
+- The package never prints the private key.
+- The gateway does not persist raw inputs or results.
+- Treat all crypto transfers as irreversible and fund only a dedicated wallet.
+
+## Development
+
+```bash
+npm install
+npm run check
+```
+
+The gateway implementation is intentionally not included in this client repository.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { getCatalog, previewUtility, runPaidUtility } from "./client.js";
+function value(flag) {
+    const index = process.argv.indexOf(flag);
+    return index >= 0 ? process.argv[index + 1] : undefined;
+}
+async function readInput() {
+    const json = value("--json");
+    const file = value("--file");
+    if ((json ? 1 : 0) + (file ? 1 : 0) !== 1)
+        throw new Error("provide exactly one of --json or --file");
+    return JSON.parse(json ?? await readFile(file, "utf8"));
+}
+const [command, utility] = process.argv.slice(2);
+if (command === "catalog") {
+    console.log(JSON.stringify(await getCatalog(), null, 2));
+}
+else if (command === "preview" && utility) {
+    console.log(JSON.stringify(await previewUtility(utility, await readInput()), null, 2));
+}
+else if (command === "call" && utility) {
+    const key = process.env.JH_EVM_PRIVATE_KEY;
+    if (!key)
+        throw new Error("JH_EVM_PRIVATE_KEY is required for a paid call");
+    console.log(JSON.stringify(await runPaidUtility(utility, await readInput(), key), null, 2));
+}
+else {
+    console.error("usage:\n  justhandled-agent catalog\n  justhandled-agent preview <utility> (--json <json> | --file <path>)\n  justhandled-agent call <utility> (--json <json> | --file <path>)");
+    process.exitCode = 2;
+}

package/dist/client.d.ts

@@ -0,0 +1,11 @@
+import { decodePaymentResponseHeader } from "@x402/core/http";
+import type { PaymentRequired, PaymentRequirements } from "@x402/core/types";
+import { type UtilityCatalog } from "./config.js";
+export interface PaidUtilityResult {
+    result: Record<string, unknown>;
+    payment: ReturnType<typeof decodePaymentResponseHeader>;
+}
+export declare function getCatalog(fetchImpl?: typeof fetch): Promise<UtilityCatalog>;
+export declare function selectGuardedRequirement(required: PaymentRequired, expectedResourceUrl?: string): PaymentRequirements;
+export declare function previewUtility(utility: string, input: unknown, fetchImpl?: typeof fetch, source?: string): Promise<PaymentRequirements>;
+export declare function runPaidUtility(utility: string, input: unknown, privateKey: `0x${string}`, fetchImpl?: typeof fetch, source?: string): Promise<PaidUtilityResult>;

package/dist/client.js

@@ -0,0 +1,78 @@
+import { decodePaymentRequiredHeader, decodePaymentResponseHeader } from "@x402/core/http";
+import { ExactEvmScheme } from "@x402/evm";
+import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
+import { privateKeyToAccount } from "viem/accounts";
+import { BASE_MAINNET, BASE_USDC, GATEWAY_ORIGIN, JUSTHANDLED_RECEIVER, PRICE_BASE_UNITS, PRICE_USDC, } from "./config.js";
+const UTILITY_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function endpointFor(utility) {
+    if (!UTILITY_ID.test(utility))
+        throw new Error("utility id must be lowercase kebab-case");
+    return `${GATEWAY_ORIGIN}/api/run/${utility}`;
+}
+function requestFor(input, source) {
+    if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(source))
+        throw new Error("source must be a bounded lowercase attribution slug");
+    return {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-jh-source": source },
+        body: JSON.stringify(input),
+    };
+}
+export async function getCatalog(fetchImpl = fetch) {
+    const response = await fetchImpl(`${GATEWAY_ORIGIN}/api/catalog`);
+    if (!response.ok)
+        throw new Error(`catalog request failed with HTTP ${response.status}`);
+    const catalog = await response.json();
+    if (!Array.isArray(catalog.utilities) || catalog.count !== catalog.utilities.length)
+        throw new Error("gateway returned a malformed catalog");
+    for (const utility of catalog.utilities) {
+        const expectedEndpoint = `${GATEWAY_ORIGIN}/api/run/${utility.id}`;
+        if (!UTILITY_ID.test(utility.id) || utility.endpoint !== expectedEndpoint || utility.price !== PRICE_USDC) {
+            throw new Error("gateway catalog contains an untrusted utility endpoint or price");
+        }
+    }
+    return catalog;
+}
+export function selectGuardedRequirement(required, expectedResourceUrl) {
+    if (expectedResourceUrl && required.resource?.url !== expectedResourceUrl) {
+        throw new Error("refusing payment: payment resource does not match the requested JustHandled endpoint");
+    }
+    const requirement = required.accepts.find((candidate) => candidate.scheme === "exact" &&
+        candidate.network === BASE_MAINNET &&
+        candidate.asset.toLowerCase() === BASE_USDC.toLowerCase() &&
+        candidate.amount === PRICE_BASE_UNITS &&
+        candidate.payTo.toLowerCase() === JUSTHANDLED_RECEIVER.toLowerCase());
+    if (!requirement) {
+        throw new Error("refusing payment: gateway requirements do not match the pinned Base network, USDC asset, $0.05 amount, and JustHandled receiver");
+    }
+    return requirement;
+}
+export async function previewUtility(utility, input, fetchImpl = fetch, source = "npm-client") {
+    const endpoint = endpointFor(utility);
+    const response = await fetchImpl(endpoint, requestFor(input, source));
+    if (response.status !== 402)
+        throw new Error(`expected an unpaid 402 preview, received HTTP ${response.status}`);
+    const header = response.headers.get("payment-required");
+    if (!header)
+        throw new Error("gateway omitted the Payment-Required header");
+    return selectGuardedRequirement(decodePaymentRequiredHeader(header), endpoint);
+}
+export async function runPaidUtility(utility, input, privateKey, fetchImpl = fetch, source = "npm-client") {
+    if (!/^0x[a-fA-F0-9]{64}$/.test(privateKey))
+        throw new Error("JH_EVM_PRIVATE_KEY must be a 32-byte hex private key");
+    await previewUtility(utility, input, fetchImpl, source);
+    const account = privateKeyToAccount(privateKey);
+    const paidFetch = wrapFetchWithPaymentFromConfig(fetchImpl, {
+        schemes: [{ network: BASE_MAINNET, client: new ExactEvmScheme(account) }],
+    });
+    const response = await paidFetch(endpointFor(utility), requestFor(input, source));
+    const paymentHeader = response.headers.get("payment-response") ?? response.headers.get("x-payment-response");
+    if (response.status !== 200 || !paymentHeader) {
+        const detail = await response.text();
+        throw new Error(`paid request failed with HTTP ${response.status}${detail ? `: ${detail.slice(0, 300)}` : ""}`);
+    }
+    return {
+        result: await response.json(),
+        payment: decodePaymentResponseHeader(paymentHeader),
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+export declare const GATEWAY_ORIGIN = "https://justhandled-agent-gateway.netlify.app";
+export declare const BASE_MAINNET = "eip155:8453";
+export declare const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+export declare const JUSTHANDLED_RECEIVER = "0xd7edc83c55c994850a14604a628639c3599665bc";
+export declare const PRICE_BASE_UNITS = "50000";
+export declare const PRICE_USDC = "$0.05";
+export interface UtilityCatalogItem {
+    id: string;
+    title: string;
+    version: string;
+    category: string;
+    summary: string;
+    price: string;
+    docsUrl: string;
+    limitations: string[];
+    inputSchema: Record<string, unknown>;
+    sampleInput: Record<string, unknown>;
+    endpoint: string;
+}
+export interface UtilityCatalog {
+    schemaVersion: string;
+    count: number;
+    utilities: UtilityCatalogItem[];
+}

package/dist/config.js

@@ -0,0 +1,6 @@
+export const GATEWAY_ORIGIN = "https://justhandled-agent-gateway.netlify.app";
+export const BASE_MAINNET = "eip155:8453";
+export const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+export const JUSTHANDLED_RECEIVER = "0xd7edc83c55c994850a14604a628639c3599665bc";
+export const PRICE_BASE_UNITS = "50000";
+export const PRICE_USDC = "$0.05";

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./client.js";
+export * from "./config.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./client.js";
+export * from "./config.js";

package/dist/mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { getCatalog, runPaidUtility } from "./client.js";
+import { PRICE_USDC } from "./config.js";
+const server = new Server({ name: "justhandled-agent-gateway", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const catalog = await getCatalog();
+    return {
+        tools: [
+            {
+                name: "justhandled_list_utilities",
+                description: "List JustHandled deterministic preflights, prices, and limitations.",
+                inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            },
+            ...catalog.utilities.map((utility) => ({
+                name: `justhandled_${utility.id.replace(/-/g, "_")}`,
+                description: `${utility.summary} Costs ${PRICE_USDC} USDC on Base mainnet.`,
+                inputSchema: utility.inputSchema,
+            })),
+        ],
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name === "justhandled_list_utilities") {
+        return { content: [{ type: "text", text: JSON.stringify(await getCatalog()) }] };
+    }
+    const catalog = await getCatalog();
+    const utility = catalog.utilities.find((candidate) => `justhandled_${candidate.id.replace(/-/g, "_")}` === request.params.name);
+    if (!utility)
+        return { content: [{ type: "text", text: "Unknown JustHandled utility" }], isError: true };
+    const key = process.env.JH_EVM_PRIVATE_KEY;
+    if (!key) {
+        return {
+            content: [{ type: "text", text: `Paid execution requires JH_EVM_PRIVATE_KEY. This tool will spend exactly ${PRICE_USDC} USDC only after validating the pinned Base network, USDC contract, price, and receiver.` }],
+            isError: true,
+        };
+    }
+    try {
+        const output = await runPaidUtility(utility.id, request.params.arguments ?? {}, key, fetch, "npm-mcp");
+        return { content: [{ type: "text", text: JSON.stringify(output) }] };
+    }
+    catch (error) {
+        return { content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }], isError: true };
+    }
+});
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@justhandledlabs/agent-client",
+  "version": "0.1.0",
+  "description": "Guarded CLI and MCP client for JustHandled's x402 utility gateway",
+  "type": "module",
+  "license": "MIT",
+  "mcpName": "com.justhandledlabs/agent-gateway",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/justhandledlabs/justhandled-agent-client.git"
+  },
+  "homepage": "https://justhandled-agent-gateway.netlify.app",
+  "bugs": {
+    "url": "https://github.com/justhandledlabs/justhandled-agent-client/issues"
+  },
+  "keywords": [
+    "ai-agents",
+    "mcp",
+    "x402",
+    "base",
+    "usdc",
+    "preflight"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "server.json"
+  ],
+  "bin": {
+    "agent-client": "dist/mcp.js",
+    "justhandled-agent-client": "dist/mcp.js",
+    "justhandled-agent": "dist/cli.js",
+    "justhandled-agent-mcp": "dist/mcp.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "node scripts/clean.mjs && tsc -p tsconfig.json",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "smoke:mcp": "npm run build && node scripts/smoke-mcp.mjs",
+    "check": "npm run build && npm test",
+    "prepack": "npm run check",
+    "prepublishOnly": "node scripts/assert-publish-ready.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "latest",
+    "@x402/core": "latest",
+    "@x402/evm": "latest",
+    "@x402/fetch": "^2.20.0",
+    "viem": "^2.55.10"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "tsx": "latest",
+    "typescript": "latest"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/server.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "com.justhandledlabs/agent-gateway",
+  "title": "JustHandled Agent Utility Gateway",
+  "description": "Ten deterministic preflights with guarded $0.05 USDC x402 execution.",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/justhandledlabs/justhandled-agent-client",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@justhandledlabs/agent-client",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "JH_EVM_PRIVATE_KEY",
+          "description": "Private key for a dedicated Base wallet funded with USDC. Never use a primary wallet.",
+          "isRequired": true,
+          "isSecret": true,
+          "format": "string"
+        }
+      ]
+    }
+  ]
+}