ln-church-agent

# ln-church-agent


**The Value of "Not a Verdict"**
LN Church read models do not decide for the agent. They preserve **observed memory**: what was seen, what was paid, what failed, what receipt shape appeared, what protocol role was observed, and what verification cost was reported. This is not a recommendation or verdict; it is a **reusable observation record** that helps the local runtime avoid re-verifying everything. Final payment authority remains local.


Your agent will hit a 402 paywall in the wild.

Will it inspect, decide, pay, recover, verify, and continue — or freeze?

`ln-church-agent` is a **buyer-side HTTP 402 runtime and agent-commerce surface inspector** for autonomous agents. 

In the broader agentic commerce stack, `ln-church-agent` acts as the buyer-side component of an observability and trust-evidence layer for HTTP 402-compatible paid actions.

It helps agents inspect paid-action surfaces, distinguish executable payment rails from higher-order commerce protocols, and prove paid execution across **L402, x402, and supported MPP** charge shapes when a concrete HTTP 402-compatible challenge, supported credential path, and verifiable receipt path are present

In v1.9.0+, the inspect layer explicitly classifies emerging agent-commerce surfaces such as **OKX Agent Payments Protocol (APP), Google AP2, and ACP** without executing payment logic. These protocols are treated as observable commerce / authorization patterns unless they expose a concrete HTTP 402-compatible settlement path.

## Supported environments

| Scope | Python | SDK v1.17.0 status |
| :--- | :--- | :--- |
| Windows | 3.11.x | Supported and recommended |
| Windows | 3.14.x | Unsupported |
| Package metadata | 3.8.1 or newer | Declared range unchanged; platform and dependency limitations still apply |

Windows上のPython 3.14では、推移依存するcoincurveの対応状況により、通常のpip installが完了しない。SDK v1.17.0ではWindows＋Python 3.14をサポート対象外とし、WindowsではPython 3.11を推奨する。

## Core Doctrine

**Do not spend even one LLM token on what the agent should not need to reason about.**

`ln-church-agent` moves payment plumbing out of the model's reasoning loop and into a deterministic buyer-side runtime.

The SDK handles mechanical HTTP 402 concerns such as:
- payment-rail inspection,
- challenge parsing,
- policy checks,
- payment execution,
- HATEOAS recovery,
- receipt verification,
- evidence capture.

The LLM remains responsible for the higher-level economic decisions:
- whether the counterparty should be trusted,
- whether payment is justified,
- whether the expected outcome was delivered,
- and whether the endpoint should be reused.

**Don't Trust, Verify. But Don't Re-Verify Everything.**

The SDK is designed for verification reuse:
agents can inspect and verify live payment flows when necessary,
but they should reuse observed memory, receipts, and read models when repeated full verification would waste context, liquidity, or reasoning budget.

## What it does

Most payment SDKs help agents *pay*.  
`ln-church-agent` helps agents complete the whole **paid-action loop**:

**Probe → Inspect → Decide → Pay → Execute → Verify → Trace**

It is designed for agents that must:
- **Inspect** HTTP 402 challenges before committing funds.
- **Choose** between L402, x402, MPP, or safe-stop paths based on local policy.
- **Execute** paid actions through policy-aware runtime controls (budgets, trust).
- **Recover** through HATEOAS-style next actions if a flow is interrupted.
- **Verify** receipts and semantic outcomes after payment.
- **Report** trace evidence to a public sandbox or local observer.
- **Record** goal-conditioned attempts and their outcomes for future optimization.

## 🧠 What this runtime is

* **Generic Buyer-Side Runtime**: A pure client-side execution engine that keeps your AI agent's reasoning loop clean by abstracting away the HTTP 402 negotiation layer.
* **Agent Commerce Surface Inspector**: Classifies emerging commerce and authorization layers such as OKX APP, AP2, ACP, and UCP separately from executable settlement rails.
* **Open-Web 402 Interoperability**: Natively supports Base64URL JSON headers, CAIP-2 network routing, and multi-chain execution out of the box.
* **Reference Sandbox Support**: Optionally integrates with the LN Church observation network for public benchmarking, trace reporting, and discovery workflows.
* **Stable Interface**: An unchanging developer API surface that safely absorbs the constant fluctuations of upstream protocol drafts.

## Two Runtime Modes

To provide safe boundaries for enterprise AI orchestration, `ln-church-agent` explicitly separates surface inspection from payment execution.

| Mode | Entrypoints | Capabilities & Safety Boundaries |
| :--- | :--- | :--- |
| **1. Inspect-only Mode** | `ln-church-agent-mcp`, `inspect` CLI | **Keyless**. Requires no private key, no wallet, and no signer. Performs no payment execution. Safe for enterprise preflight and classification. Classifies HTTP 402 and agent-commerce surfaces (AP2/ACP/APP). Outputs guided handoff, settlement options, and safe next steps (`observe_only` or `stop_safely`). |
| **2. Execution Runtime Mode** | `Payment402Client`, `LnChurchClient` | May use a private key, wallet, LN adapter, or supported EVM signer for executable rails. Canonical SVM exact remains inspect-only and fail-closed; configured SVM key material does not enable its high-level execution. Performs the supported `Pay → Execute → Verify → Trace` loop. Does not auto-submit telemetry unless explicitly called. |
| **3. Read-only Memory** | `get_surface_preflight()` | Fetches public-safe observed memory for a surface without executing payments or interacting with the target. |
| **4. Explicit Telemetry** | `submit_goal_attempt_observation()`, `submit_external_observation()` | Explicit-only telemetry submission. Never auto-submits from standard execution paths. |
| **5. Public Agent Task Worker** | `AgentTaskClient`, `ln-church-agent task` | Synchronous, wallet-keyless and no-payment discovery and completion of `payment_surface_discovery.v1` Tasks at the fixed LN Church origin. The Host Agent discovers the target surface; the SDK validates and registers the public-safe result. |

### Public Agent Task worker boundary (v1.17.0 candidate)

The canonical Task Venue interface is the public Hondo API. `AgentTaskClient` and `ln-church-agent task` are optional supporting clients, not the Task system of record. `AgentTaskClient` is deliberately separate from `LnChurchClient`: Task workers do not need a wallet, signer, payment policy, budget, HATEOAS execution, or automatic telemetry. The client supports only the fixed `https://kari.mayim-mayim.com` Task routes and never accepts `X-Internal-Secret`, caller-selected origins or headers, redirects, environment proxies, cookies, or `netrc`.

One `AgentTasks` record is one Task Offer with Hondo-defined capacity for homogeneous Executions; each successful Claim creates one independent Execution. Hondo applies a capacity-only policy: while unconsumed reward capacity remains, multiple Executions may be active concurrently, and there is no separate Task-level single-active concurrency limit. The canonical Alpha contract records A=`1000000`, B=`10000`, N=50, and maximum reward principal=`500000` atomic USDC as policy evidence. Those values are not SDK behavior. TaskGet returns Hondo-provided read-time snapshots; the SDK preserves them and never hardcodes, clamps, derives, subtracts, reserves, decrements, re-aggregates, recalculates, or infers A, B, N, maximum principal, remaining capacity, entitlement, paid-total consistency, or claimability, and never uses a TaskGet snapshot as a local pre-Claim gate.

Task list and detail retain the server-provided `active_execution_count`, `claim_count_total`, `rewarded_execution_count`, `reward_paid_total_minor`, `capacity_total`, `capacity_remaining`, `maximum_reward_principal_atomic`, `claimable`, and `poc_terms` exactly as a read-time snapshot. The client validates only wire types and field-local constraints: `active_execution_count` is an exact non-negative integer, including values of 2 or more; `claim_count_total`, `rewarded_execution_count`, `reward_paid_total_minor`, and `capacity_remaining` are exact non-negative integers; `capacity_total` is an exact positive integer; `maximum_reward_principal_atomic` is a canonical positive atomic string; and `claimable` is an exact boolean. Booleans never pass as integer counters. The SDK accepts, preserves, and displays a wire-valid snapshot without clamping even when derived relationships among its fields disagree; it does not infer Offer policy, capacity, entitlement, paid-total consistency, or claimability. Offer `OPEN`, `claimable`, and `capacity_remaining` are read-time metadata rather than a prediction or guarantee that a later Claim will succeed.

Each Task and successful Claim retains a frozen `TaskDefinitionReference`: the API-supplied Definition version and digest plus the exact manifest URL and manifest digest. These are public immutable metadata, not executable instructions. The SDK does not resolve `latest`, construct a storage key or URL, download a Definition bundle, or execute its contents.

The Claim response discloses its lease-bound token once. The token and private credential are Claim-specific—not merely task-level—and remain usable only for that Claim's Observation and Completion calls until lease expiry. They are excluded from normal representations, dumps, JSON, logs, exceptions, and CLI output. The `task claim` CLI stores the complete immutable Claim snapshot, including the successful Claim's authoritative reward terms, only through an explicit create-exclusive private credential-file operation; an outcome that may have committed leaves a secret-free `CLAIM_OUTCOME_UNKNOWN` tombstone and is never replayed automatically. The Claim-time `reward_address` is only a payout destination; it is never the Agent principal, an identity proof, or proof of wallet control. Mu