@aifinpay/skill 2.8.0 → 2.9.0

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "aifinpay",
       "source": "./",
       "description": "Payment rail skills for paying agents and API merchants.",
-      "version": "2.8.0",
+      "version": "2.9.0",
       "author": {
         "name": "AiFinPay Support",
         "email": "contact@aifinpay.io"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aifinpay",
   "description": "Payment rail for AI agents: pay for x402 APIs or charge agents for yours.",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "author": { "name": "AiFinPay Support" },
   "homepage": "https://aifinpay.io",
   "repository": "https://github.com/AiFinPay/skill",

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 2.9.0 — reporting cohort source candidate
+
+- Align package, lock, plugin and both skill versions with the coordinated
+  MCP2.8.0 / Node SDK2.6.0 / Python SDK2.5.1 release target; preserve dated
+  published baselines without claiming this cohort is published or active.
+- Describe the explicit merchant reporting v2 target for Node gate0.4.0 and
+  Python gate0.1.3: observed challenge/admission/completion, consent and
+  memory-only capabilities, bounded queue loss and acknowledged producer health.
+  Observations do not establish verified identity, payment or complete coverage.
+- Keep the existing gated MCP tools, signing, receipt/budget/recovery and
+  network activation requirements. Canonical payer bytes must be copied into
+  the paired MCP build before its exact cohort and registry release gates.
+- Validate matching payer/merchant/README targets, dated payer publication
+  baseline and changelog metadata; test drift refusals without dependencies.
+
 ## 2.8.0 — source candidate
 
 - Describe the MCP2.7 / Node and Python2.5 Solana source target with explicit

package/README.md

@@ -9,8 +9,13 @@ any client that loads `SKILL.md`).
 | `aifinpay` | Paying — agent buys x402-gated API access | `agent/skills/aifinpay/SKILL.md` |
 | `aifinpay-merchant` | Earning — merchant charges agents per request | `agent/skills/aifinpay-merchant/SKILL.md` |
 
-Version2.8.0 describes the coordinated MCP2.7.0 / Node and Python SDK2.5.0
-release target, including the Solana source adapter. Canonical disabled Solana
+Version **2.9.0** describes a coordinated reporting release target.
+Release target: MCP **2.8.0**, Node SDK **2.6.0**, Python **2.5.1**.
+Reporting release target: Node gate **0.4.0**, Python gate **0.1.3**.
+The merchant guide describes explicit opt-in observations, consent, queue loss
+and producer health using the SDK's reporting v2 contract. It adds no MCP tools
+or signing authority and does not establish publication or partner rollout.
+The payer guide retains the Solana source adapter. Canonical disabled Solana
 records remain unavailable until accepted and served. Its nine EVM descriptors
 require explicit owner and merchant
 network consent plus backend readiness; installing instructions does not
@@ -21,6 +26,13 @@ Rule of thumb: if the user wants to **pay** for a paid API, load `aifinpay`.
 If they **own** a site/API agents visit, load `aifinpay-merchant` — and mention
 the other side exists.
 
+For merchant reporting, follow the merchant guide's optional reporting section
+and the SDK's [Node](https://github.com/AiFinPay/sdk/blob/main/gate/REPORTING-V2.md)
+or [Python](https://github.com/AiFinPay/sdk/blob/main/python-gate/REPORTING-V2.md)
+instructions. Observation events, admission and resource completion are
+distinct; payments require confirmed settlement evidence. Producer health
+and pending/drop coverage describe telemetry completeness, not payment success.
+
 ## Install
 
 Install the skills with the `skills` CLI:

package/agent/skills/aifinpay/SKILL.md

@@ -6,7 +6,7 @@ description: Pay for x402-gated APIs and sites as an agent (AIFP-1 on an owner-s
   wallet, payment history, prepaid quotas and Agent Passport records through
   the AiFinPay MCP server or SDK.
 license: MIT
-version: 2.8.0
+version: 2.9.0
 author: AiFinPay Support
 metadata:
   hermes:
@@ -61,7 +61,7 @@ your language. There is no "install together" scenario.
 
 ## Version and release status
 
-Release target: MCP **2.7.0**, Node SDK **2.5.0**, Python **2.5.0**.
+Release target: MCP **2.8.0**, Node SDK **2.6.0**, Python **2.5.1**.
 This skill describes that coordinated package cohort. Check the installed
 versions before using its additional-network instructions; a release target
 does not establish npm/PyPI publication or production network activation.
@@ -71,8 +71,8 @@ Published packages remain usable within their documented capabilities.
 
 | Surface | Can it pay? |
 |---|---|
-| MCP `@aifinpay/mcp` 2.7.x | `payable_fetch`, only with a persistent wallet and every owner limit set. Polygon is the default; other networks require explicit `AIFINPAY_PAY_CHAIN`. The merchant and backend must authorize and serve that network. `scope: "merchant"` buys a site-wide batch. |
-| Node `@aifinpay/agent` 2.5.x | `fetchPaid` with a v14 journal, gas cap and owner budgets. Select another network with `v14.chain`; select a pinned stablecoin with `v14.asset`. Native payments require an independent native/USD rate. |
+| MCP `@aifinpay/mcp` 2.8.x | `payable_fetch`, only with a persistent wallet and every owner limit set. Polygon is the default; other networks require explicit `AIFINPAY_PAY_CHAIN`. The merchant and backend must authorize and serve that network. `scope: "merchant"` buys a site-wide batch. |
+| Node `@aifinpay/agent` 2.6.x | `fetchPaid` with a v14 journal, gas cap and owner budgets. Select another network with `v14.chain`; select a pinned stablecoin with `v14.asset`. Native payments require an independent native/USD rate. |
 | Python `aifinpay-agent` 2.5.x | `agent.fetch_paid(url, allowed_origins=…, max_amount_usd=…, daily_amount_usd=…)`; use explicit `chain` and the chain's native gas cap for another network, or a pinned stablecoin `asset`. `agent.recover_paid(journal_path)` recovers the original transaction. |
 
 The client descriptors below are shared by the target cohort. They do not
@@ -166,7 +166,7 @@ or event log alone does not prove a valid paid request.
 
 # AiFinPay agent workflow
 
-Use the tools actually returned by MCP tools/list. MCP 2.7.0 exposes
+Use the tools actually returned by MCP tools/list. MCP 2.8.0 exposes
 agent_address, agent_reload, agent_claim_self, agent_history, agent_quota,
 agent_passport_resolve, settlement_routes, settlement_invoice and
 deployment_info; `payable_fetch` appears when the owner has enabled payments.

package/agent/skills/aifinpay-merchant/SKILL.md

@@ -4,7 +4,7 @@ description: Configure an HTTP 402 gate for agent access to a website or API,
   with owner-selected routes, verified payouts and explicitly accepted EVM
   networks. Agents settle from their own wallets; the merchant receives 99%.
 license: MIT
-version: 2.8.0
+version: 2.9.0
 author: AiFinPay Support
 metadata:
   hermes:
@@ -155,7 +155,9 @@ Gate 0.3.3 source adds `instructions_url` (payer skill),
 links to maintained public instructions, not stored wallet or receipt data.
 Existing sites must upgrade/redeploy gate to emit those new fields.
 
-This skill's release target is MCP2.7.0 and Node/Python SDK2.5.0. Those clients
+Release target: MCP **2.8.0**, Node SDK **2.6.0**, Python **2.5.1**.
+This coordinated target does not establish publication or reporting rollout.
+Those clients
 reuse the signed v1.4 payment kernel for nine EVM network descriptors; network
 metadata does not activate a deployment or verifier. Production served Polygon
 and Base at the 2026-10-04 baseline check. Additional networks require a ready
@@ -178,6 +180,62 @@ network until their owner updates them. Read the selected issuer's
 payment readiness. Do not change a payout wallet, accepted network set or
 settlement version without the merchant owner's authorization.
 
+## Optional observation and reporting
+
+Reporting release target: Node gate **0.4.0**, Python gate **0.1.3**.
+Use these instructions only after checking the installed packages and the
+backend's reporting v2 readiness. Installing the skill does not enable reporting
+or verify a partner integration. Opt in when the merchant owner requests it:
+Node uses `createGateReporterV2` with `reporting: { version: 2, reporter,
+context }`; Python uses `GateReporterV2` with `Gate(..., reporting=reporter,
+reporting_context=...)`. Keep the existing receipt verification and shared
+quota store. Use one producer per merchant per worker, created after fork in
+Python; do not also attach the legacy `onEvent`/`on_event` reporter or report
+the same request through both hosted and self-hosted instrumentation.
+
+Declare only stages the adapter actually observes: `access_challenged` for an
+emitted 402, `access_admitted` before the paid handler, and
+`resource_response_completed` for its terminal success, redirect, error or
+abort. A challenge is not a browser view; admission is not completion.
+Neither stage counts a verified unique agent or proves payment. Payments and
+revenue require confirmed settlement evidence, never purchased quota or
+invented historical usage. Browser observations need their separate API;
+the gate producer does not infer them from User-Agent or `AIFP-Agent-Id`.
+
+Context carries an explicit channel and consent state. Only granted consent
+allows an optional random, site-scoped `client_id`; it remains unverified.
+Do not derive identity from a wallet, IP, fingerprint, headers or request body.
+An optional flow minted by `mintFlow`/`mint_flow` carries a short-lived
+`reporting_token` for observation only. It grants no access, payment authority,
+ownership or integration verification. Keep it in memory, outside URLs,
+logs, browser storage, cookies and payment/recovery files. The payer SDK's
+optional `reportingToken`/`reporting_token` reaches only its fixed first-party
+quote endpoints; never manually forward it to merchant, pay, RPC or JWKS
+requests. Reporting failures preserve the original access/payment result.
+
+Keep the merchant secret server-side. Report only registered route patterns,
+never full URLs, queries, bodies, raw headers, IPs, receipt JWTs or wallet IDs.
+Queues are in memory, bounded to 1000 events, with batches of at most 50,
+3-second request deadlines and at most 5 attempts within 15 minutes.
+Retries retain the same event IDs, timestamps and facts; outages, overflow
+and crashes lose observations. Permanent errors and redirects are not retried;
+fix credentials/configuration before replacing a stopped producer.
+
+Node health auto-samples every 60 seconds; Python normally samples every 5
+seconds. All health attempts are at least 5 seconds apart, and retries may
+delay samples. A health acknowledgement is exactly `{version: 2, duplicate: boolean}`,
+separate from the event-batch acknowledgement. Until a sample is acknowledged,
+remote pending/drop coverage is unknown; a health gap over 5 minutes remains
+a coverage gap. Local counters and successful HTTP responses do not prove a
+complete report, and superseding lifetime health counters must not be summed.
+Drain HTTP requests before closing the producer in the existing shutdown hook;
+flush/close do not promise delivery.
+
+Read the exact wiring and consent/loss rules before implementation:
+[Node reporting v2](https://github.com/AiFinPay/sdk/blob/main/gate/REPORTING-V2.md)
+and [Python reporting v2](https://github.com/AiFinPay/sdk/blob/main/python-gate/REPORTING-V2.md).
+This reporting target adds no MCP tools or signing authority.
+
 ## Register the site (get your merchant_id)
 
 The gate needs a `merchant_id`. Two ways to get one:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifinpay/skill",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "AiFinPay agent skills: pay for x402-gated APIs as an agent (aifinpay) and charge agents for your API as a merchant (aifinpay-merchant).",
   "type": "module",
   "files": [
@@ -11,7 +11,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node scripts/validate.mjs",
+    "test": "node scripts/validate.mjs && node --test scripts/validate.test.mjs",
     "prepublishOnly": "npm test"
   },
   "keywords": [