@justhandledlabs/agent-client 0.6.0 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # JustHandled Agent Client
 
-A guarded CLI, JavaScript client, and local MCP server for the [JustHandled Agent Utility Gateway](https://justhandledlabs.com/agent-gateway/). The package exposes twenty-seven deterministic preflights, maintained-data lookups, and evidence products. Twenty-two products cost $0.05 USDC; five evidence-heavy products cost $0.25, including Agent Distribution Readiness and Community Rule & Credibility Preflight. Every paid call returns a versioned evidence receipt.
+A guarded CLI, JavaScript client, and local MCP server for the [JustHandled Agent Utility Gateway](https://justhandledlabs.com/agent-gateway/). The package exposes twenty-nine deterministic preflights, maintained-data lookups, and evidence products. Twenty-two products cost $0.05 USDC; seven evidence-heavy products cost $0.25, including Agent Distribution Readiness, Community Rule & Credibility Preflight, Qualified Demand Ledger, and Channel-Fit Evidence Matrix. Every paid call returns a versioned evidence receipt.
 
 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.
 
@@ -12,6 +12,8 @@ npx --package @justhandledlabs/agent-client justhandled-agent preview filename-p
 npx --package @justhandledlabs/agent-client justhandled-agent preview agent-run-evidence-pack --file agent-run-evidence-pack.sample.json
 npx --package @justhandledlabs/agent-client justhandled-agent preview agent-distribution-readiness-pack --file agent-distribution-readiness-pack.sample.json
 npx --package @justhandledlabs/agent-client justhandled-agent preview community-rule-credibility-preflight --file community-rule-credibility-preflight.sample.json
+npx --package @justhandledlabs/agent-client justhandled-agent preview qualified-demand-ledger --file qualified-demand-ledger.sample.json
+npx --package @justhandledlabs/agent-client justhandled-agent preview channel-fit-evidence-matrix --file channel-fit-evidence-matrix.sample.json
 ```
 
 Preview performs an unpaid request and validates the returned x402 terms. It does not sign or spend.
@@ -59,7 +61,7 @@ The package declares the official MCP Registry identity `io.github.justhandledla
 ## Security model
 
 - Price, chain, asset, receiver, and gateway origin are pinned in code.
-- The five $0.25 products' 250,000-base-unit price is pinned separately from 50,000-base-unit checks.
+- The seven $0.25 products' 250,000-base-unit price is pinned separately from 50,000-base-unit checks.
 - Every execution starts with an unpaid 402 preview.
 - A mismatched term aborts before signing.
 - The package never prints the private key.

package/dist/config.js

@@ -13,6 +13,8 @@ export const QUARTER_DOLLAR_UTILITIES = new Set([
     "site-discovery-change-packet",
     "agent-distribution-readiness-pack",
     "community-rule-credibility-preflight",
+    "qualified-demand-ledger",
+    "channel-fit-evidence-matrix",
 ]);
 export function expectedPriceForUtility(utility) {
     return QUARTER_DOLLAR_UTILITIES.has(utility) ? AGENT_RUN_EVIDENCE_PACK_PRICE_USDC : PRICE_USDC;

package/dist/mcp.js

@@ -3,7 +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";
-const server = new Server({ name: "justhandled-agent-gateway", version: "0.6.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "justhandled-agent-gateway", version: "0.8.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     const catalog = await getCatalog();
     return {

package/examples/channel-fit-evidence-matrix.sample.json

@@ -0,0 +1,94 @@
+{
+  "observed_at": "2026-08-01T22:30:00Z",
+  "objective": "qualified-demand",
+  "constraints": {
+    "budget_usd": 50,
+    "effort_hours": 12,
+    "max_parallel_tests": 2,
+    "rules_max_age_days": 30
+  },
+  "evidence": [
+    {
+      "id": "rule-agent-directory",
+      "type": "platform-rule",
+      "captured_at": "2026-08-01T20:00:00Z",
+      "source_url": "https://example.com/directory-rules",
+      "observed": true
+    },
+    {
+      "id": "rule-marketplace",
+      "type": "platform-rule",
+      "captured_at": "2026-08-01T20:10:00Z",
+      "source_url": "https://example.com/marketplace-rules",
+      "observed": true
+    },
+    {
+      "id": "proof-live",
+      "type": "product-proof",
+      "captured_at": "2026-08-01T21:00:00Z",
+      "source_url": "https://example.com/product",
+      "observed": true
+    },
+    {
+      "id": "proof-readiness",
+      "type": "distribution-readiness",
+      "captured_at": "2026-08-01T21:10:00Z",
+      "source_url": "https://example.com/readiness-receipt",
+      "observed": true
+    }
+  ],
+  "channels": [
+    {
+      "id": "agent-directory",
+      "kind": "agent-directory",
+      "audience_match": 5,
+      "buyer_intent": 4,
+      "format_match": 5,
+      "saturation": 3,
+      "rule_status": "verified",
+      "rule_evidence_id": "rule-agent-directory",
+      "product_evidence_ids": ["proof-live", "proof-readiness"],
+      "attribution": "verified",
+      "attribution_mechanism": "Unique source token preserved through the unpaid challenge and settlement receipt.",
+      "existing_access": "account",
+      "offer_path_ready": true,
+      "estimated_cost_usd": 0,
+      "estimated_effort_hours": 2,
+      "owner_presence_required": false,
+      "owner_available": true,
+      "outcome_gate": {
+        "metric": "payment-initiation",
+        "threshold": 2,
+        "window_days": 14,
+        "max_cost_usd": 0,
+        "max_effort_hours": 4
+      }
+    },
+    {
+      "id": "marketplace",
+      "kind": "marketplace",
+      "audience_match": 4,
+      "buyer_intent": 5,
+      "format_match": 4,
+      "saturation": 4,
+      "rule_status": "verified",
+      "rule_evidence_id": "rule-marketplace",
+      "product_evidence_ids": ["proof-live"],
+      "attribution": "direct",
+      "attribution_mechanism": "Marketplace listing identifier linked to checkout-opening evidence.",
+      "existing_access": "account",
+      "offer_path_ready": true,
+      "estimated_cost_usd": 0,
+      "estimated_effort_hours": 3,
+      "owner_presence_required": false,
+      "owner_available": true,
+      "outcome_gate": {
+        "metric": "checkout-open",
+        "threshold": 2,
+        "window_days": 14,
+        "max_cost_usd": 0,
+        "max_effort_hours": 5
+      }
+    }
+  ]
+}

package/examples/qualified-demand-ledger.sample.json

@@ -0,0 +1,71 @@
+{
+  "observed_at": "2026-08-04T18:00:00Z",
+  "window": {
+    "started_at": "2026-08-01T00:00:00Z",
+    "ended_at": "2026-08-04T17:59:59Z"
+  },
+  "events": [
+    {
+      "id": "view-1",
+      "type": "impression",
+      "occurred_at": "2026-08-01T12:00:00Z",
+      "source": "directory",
+      "evidence_ref": "analytics:impression:1",
+      "owner_controlled": false,
+      "external_actor": false,
+      "attribution": "none"
+    },
+    {
+      "id": "question-1",
+      "type": "buyer-question",
+      "occurred_at": "2026-08-01T13:00:00Z",
+      "source": "support",
+      "evidence_ref": "ticket:question:1",
+      "owner_controlled": false,
+      "external_actor": true,
+      "attribution": "direct",
+      "actor_token": "actor:7f91c2a8",
+      "product_id": "example-product"
+    },
+    {
+      "id": "settlement-1",
+      "type": "external-settlement",
+      "occurred_at": "2026-08-01T14:00:00Z",
+      "source": "payment-processor",
+      "evidence_ref": "receipt:settlement:1",
+      "owner_controlled": false,
+      "external_actor": true,
+      "attribution": "verified",
+      "actor_token": "actor:7f91c2a8",
+      "product_id": "example-product",
+      "amount": 19,
+      "currency": "USD",
+      "transaction_id": "txn_example_1"
+    },
+    {
+      "id": "value-1",
+      "type": "measured-review-time-reduction",
+      "occurred_at": "2026-08-02T16:00:00Z",
+      "source": "timed-review",
+      "evidence_ref": "measurement:review:1",
+      "owner_controlled": false,
+      "external_actor": true,
+      "attribution": "verified",
+      "measured_value": 12,
+      "measurement_unit": "minutes"
+    },
+    {
+      "id": "return-1",
+      "type": "recurring-use",
+      "occurred_at": "2026-08-03T16:00:00Z",
+      "source": "usage-receipt",
+      "evidence_ref": "receipt:usage:2",
+      "owner_controlled": false,
+      "external_actor": true,
+      "attribution": "verified",
+      "actor_token": "actor:7f91c2a8",
+      "product_id": "example-product",
+      "parent_event_id": "settlement-1"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justhandledlabs/agent-client",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Guarded CLI and MCP client for JustHandled's x402 utility gateway",
   "type": "module",
   "license": "MIT",

package/server.json

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.justhandledlabs/agent-gateway",
   "title": "JustHandled Agent Utility Gateway",
-  "description": "Twenty-seven guarded pay-per-call preflights and evidence products over USDC x402.",
-  "version": "0.6.0",
+  "description": "Twenty-nine guarded pay-per-call preflights and evidence products over USDC x402.",
+  "version": "0.8.0",
   "repository": {
     "url": "https://github.com/justhandledlabs/justhandled-agent-client",
     "source": "github"
@@ -12,7 +12,7 @@
     {
       "registryType": "npm",
       "identifier": "@justhandledlabs/agent-client",
-      "version": "0.6.0",
+      "version": "0.8.0",
       "transport": {
         "type": "stdio"
       },