@justhandledlabs/agent-client 0.1.1 → 0.2.1

package/README.md

@@ -1,18 +1,21 @@
 # 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 sixteen deterministic preflights, including six agent evidence and evaluation checks. Each paid call costs exactly $0.05 USDC on Base mainnet and returns a versioned evidence receipt.
+A guarded CLI, JavaScript client, and local MCP server for the [JustHandled Agent Utility Gateway](https://justhandled-agent-gateway.netlify.app). The package exposes twenty deterministic preflights and evidence products. Nineteen individual checks cost $0.05 USDC; the consolidated six-check Agent Run Evidence Pack costs $0.25. Every paid call 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.
+The client fails closed before signing. It accepts only the pinned JustHandled gateway, Base mainnet, canonical Base USDC, the exact per-product 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"]}'
+npx --package @justhandledlabs/agent-client justhandled-agent preview agent-run-evidence-pack --file agent-run-evidence-pack.sample.json
 ```
 
 Preview performs an unpaid request and validates the returned x402 terms. It does not sign or spend.
 
+The catalog includes API-response contract drift, webhook contract and replay, and policy-change evidence products. Packaged example inputs are available in `examples/`.
+
 Machine-readable products, exact payment terms, and free deterministic fixtures are available from the gateway's [product catalog](https://justhandled-agent-gateway.netlify.app/api/product-catalog), [OpenAPI document](https://justhandled-agent-gateway.netlify.app/openapi.json), and [sandbox index](https://justhandled-agent-gateway.netlify.app/sandbox/index.json).
 
 ## Execute one paid utility
@@ -52,6 +55,7 @@ The MCP server exposes a free catalog tool plus one paid tool per gateway utilit
 ## Security model
 
 - Price, chain, asset, receiver, and gateway origin are pinned in code.
+- The Agent Run Evidence Pack's 250,000-base-unit price is pinned separately from 50,000-base-unit individual checks.
 - Every execution starts with an unpaid 402 preview.
 - A mismatched term aborts before signing.
 - The package never prints the private key.

package/dist/client.js

@@ -2,13 +2,23 @@ import { decodePaymentRequiredHeader, decodePaymentResponseHeader } from "@x402/
 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";
+import { BASE_MAINNET, BASE_USDC, GATEWAY_ORIGIN, JUSTHANDLED_RECEIVER, expectedBaseUnitsForUtility, expectedPriceForUtility, } 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 utilityFromEndpoint(resourceUrl) {
+    const url = new URL(resourceUrl);
+    if (url.origin !== GATEWAY_ORIGIN || url.search || url.hash || url.username || url.password) {
+        throw new Error("refusing payment: payment resource is not a canonical JustHandled endpoint");
+    }
+    const match = /^\/api\/run\/([a-z0-9]+(?:-[a-z0-9]+)*)$/.exec(url.pathname);
+    if (!match)
+        throw new Error("refusing payment: payment resource is not a canonical JustHandled endpoint");
+    return match[1];
+}
 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");
@@ -27,7 +37,7 @@ export async function getCatalog(fetchImpl = fetch) {
         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) {
+        if (!UTILITY_ID.test(utility.id) || utility.endpoint !== expectedEndpoint || utility.price !== expectedPriceForUtility(utility.id)) {
             throw new Error("gateway catalog contains an untrusted utility endpoint or price");
         }
     }
@@ -37,13 +47,19 @@ 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 resourceUrl = expectedResourceUrl ?? required.resource?.url;
+    if (!resourceUrl)
+        throw new Error("refusing payment: payment resource is missing");
+    const utility = utilityFromEndpoint(resourceUrl);
+    const expectedAmount = expectedBaseUnitsForUtility(utility);
+    const expectedDisplay = expectedPriceForUtility(utility);
     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.amount === expectedAmount &&
         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");
+        throw new Error(`refusing payment: gateway requirements do not match the pinned Base network, USDC asset, ${expectedDisplay} amount, and JustHandled receiver`);
     }
     return requirement;
 }

package/dist/config.d.ts

@@ -4,6 +4,11 @@ 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 declare const AGENT_RUN_EVIDENCE_PACK = "agent-run-evidence-pack";
+export declare const AGENT_RUN_EVIDENCE_PACK_BASE_UNITS = "250000";
+export declare const AGENT_RUN_EVIDENCE_PACK_PRICE_USDC = "$0.25";
+export declare function expectedPriceForUtility(utility: string): string;
+export declare function expectedBaseUnitsForUtility(utility: string): string;
 export interface UtilityCatalogItem {
     id: string;
     title: string;
@@ -16,6 +21,7 @@ export interface UtilityCatalogItem {
     inputSchema: Record<string, unknown>;
     sampleInput: Record<string, unknown>;
     endpoint: string;
+    priceBaseUnits?: string;
 }
 export interface UtilityCatalog {
     schemaVersion: string;

package/dist/config.js

@@ -4,3 +4,12 @@ export const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
 export const JUSTHANDLED_RECEIVER = "0xd7edc83c55c994850a14604a628639c3599665bc";
 export const PRICE_BASE_UNITS = "50000";
 export const PRICE_USDC = "$0.05";
+export const AGENT_RUN_EVIDENCE_PACK = "agent-run-evidence-pack";
+export const AGENT_RUN_EVIDENCE_PACK_BASE_UNITS = "250000";
+export const AGENT_RUN_EVIDENCE_PACK_PRICE_USDC = "$0.25";
+export function expectedPriceForUtility(utility) {
+    return utility === AGENT_RUN_EVIDENCE_PACK ? AGENT_RUN_EVIDENCE_PACK_PRICE_USDC : PRICE_USDC;
+}
+export function expectedBaseUnitsForUtility(utility) {
+    return utility === AGENT_RUN_EVIDENCE_PACK ? AGENT_RUN_EVIDENCE_PACK_BASE_UNITS : PRICE_BASE_UNITS;
+}

package/dist/mcp.js

@@ -3,8 +3,7 @@ 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: {} } });
+const server = new Server({ name: "justhandled-agent-gateway", version: "0.2.1" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     const catalog = await getCatalog();
     return {
@@ -16,7 +15,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             ...catalog.utilities.map((utility) => ({
                 name: `justhandled_${utility.id.replace(/-/g, "_")}`,
-                description: `${utility.summary} Costs ${PRICE_USDC} USDC on Base mainnet.`,
+                description: `${utility.summary} Costs ${utility.price} USDC on Base mainnet.`,
                 inputSchema: utility.inputSchema,
             })),
         ],
@@ -33,7 +32,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     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.` }],
+            content: [{ type: "text", text: `Paid execution requires JH_EVM_PRIVATE_KEY. This tool will spend exactly ${utility.price} USDC only after validating the pinned Base network, USDC contract, price, and receiver.` }],
             isError: true,
         };
     }

package/examples/agent-run-evidence-pack.sample.json

@@ -0,0 +1,24 @@
+{
+  "promise_action": {
+    "promises": [{ "id": "p1", "description": "Publish package" }],
+    "actions": [{ "id": "a1", "status": "completed", "promise_ids": ["p1"], "evidence_ids": ["e1"] }],
+    "evidence": [{ "id": "e1", "type": "registry", "uri": "https://registry.example/package" }]
+  },
+  "tool_calls": {
+    "contracts": [{ "tool": "publish", "allowed": true, "max_calls": 1, "required_arguments": ["artifact"], "forbidden_arguments": ["private_key"] }],
+    "calls": [{ "id": "c1", "tool": "publish", "arguments": { "artifact": "package.tgz" }, "outcome": "published" }]
+  },
+  "completion": {
+    "outcomes": [{ "id": "publish", "status": "completed", "evidence": [{ "type": "registry", "uri": "https://registry.example/package" }] }]
+  },
+  "tool_descriptions": {
+    "tools": [{ "name": "publish", "description": "Publish one validated package artifact to the configured registry.", "inputs": ["artifact"], "outputs": ["registry receipt"], "side_effects": ["creates a public package version"], "failure_modes": ["registry rejection"], "cost": { "amount": "0", "currency": "USD" }, "idempotency": "fails if the version already exists" }]
+  },
+  "skill_activation": {
+    "cases": [{ "id": "publish-package", "expected_skills": ["publish"], "observed_skills": ["publish"] }]
+  },
+  "costs": {
+    "budget_usd": 0.1,
+    "calls": [{ "id": "turn-1", "model": "example-model", "input_tokens": 1000, "output_tokens": 250, "input_usd_per_million": 1, "output_usd_per_million": 4, "tool_cost_usd": 0.01 }]
+  }
+}

package/examples/api-response-contract-drift.json

@@ -0,0 +1,18 @@
+{
+  "contracts": [{
+    "id": "get-account",
+    "expected_status": 200,
+    "expected_content_type": "application/json",
+    "required_fields": ["data.id", "data.status"],
+    "forbidden_fields": ["data.secret"],
+    "field_types": { "data.id": "string", "data.status": "string" },
+    "stable_values": { "data.status": "active" }
+  }],
+  "responses": [{
+    "id": "run-1",
+    "contract_id": "get-account",
+    "status": 200,
+    "content_type": "application/json",
+    "body": { "data": { "id": "acct-1", "status": "active" } }
+  }]
+}

package/examples/filename-portability.json

@@ -0,0 +1,6 @@
+{
+  "paths": [
+    "CON.txt",
+    "docs/Guide.pdf"
+  ]
+}

package/examples/policy-change-evidence.json

@@ -0,0 +1,15 @@
+{
+  "policies": [{
+    "id": "refund-policy",
+    "baseline": {
+      "version": "1.0",
+      "effective_date": "2026-01-01",
+      "clauses": [{ "id": "window", "text": "Refunds are available within 30 days.", "applies_to": ["all customers"], "requirements": ["receipt"] }]
+    },
+    "current": {
+      "version": "1.0",
+      "effective_date": "2026-01-01",
+      "clauses": [{ "id": "window", "text": "Refunds are available within 30 days.", "applies_to": ["all customers"], "requirements": ["receipt"] }]
+    }
+  }]
+}

package/examples/webhook-contract-replay.json

@@ -0,0 +1,20 @@
+{
+  "observed_at": "2026-08-01T15:00:00.000Z",
+  "contracts": [{
+    "event": "invoice.paid",
+    "allowed_versions": ["2026-01"],
+    "required_fields": ["invoice.id", "invoice.amount"],
+    "signature_required": true,
+    "idempotency_required": true,
+    "max_age_seconds": 300
+  }],
+  "deliveries": [{
+    "id": "delivery-1",
+    "event": "invoice.paid",
+    "version": "2026-01",
+    "payload": { "invoice": { "id": "inv-1", "amount": 2500 } },
+    "signature_present": true,
+    "idempotency_key": "evt-1",
+    "event_created_at": "2026-08-01T14:58:00.000Z"
+  }]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justhandledlabs/agent-client",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Guarded CLI and MCP client for JustHandled's x402 utility gateway",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,7 @@
   ],
   "files": [
     "dist",
+    "examples",
     "README.md",
     "LICENSE",
     "server.json"

package/server.json

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "com.justhandledlabs/agent-gateway",
   "title": "JustHandled Agent Utility Gateway",
-  "description": "Sixteen deterministic preflights with guarded $0.05 USDC x402 execution.",
-  "version": "0.1.1",
+  "description": "Twenty deterministic preflights and evidence products with guarded per-product USDC x402 execution.",
+  "version": "0.2.1",
   "repository": {
     "url": "https://github.com/justhandledlabs/justhandled-agent-client",
     "source": "github"
@@ -12,7 +12,7 @@
     {
       "registryType": "npm",
       "identifier": "@justhandledlabs/agent-client",
-      "version": "0.1.1",
+      "version": "0.2.1",
       "transport": {
         "type": "stdio"
       },