ln-church-agent

# ln-church-agent

## Unreleased 1.18.11: seven-day listing contracts

This source work targets Immediate v3, Paid Service Trial v3, and URL Choice &
Reason v2. Version 1.18.11 is candidate metadata, not a published SDK release.
The DC-fixed producer packs are bundled. Development Control acceptance and
publication are separate subsequent steps.

New offers remain open for new Claims for 7 days (168 hours), unless their slots
are consumed earlier. Existing Claim deadlines are unchanged. Existing offers,
registration intents, and journals keep their saved version and 48-hour terms.
Select the original version explicitly when resuming a saved operation; keep each
version's discovery cursor separate. Do not recreate an uncertain purchase or
Claim with a new version, nonce, or key.

This update removes the service's 0.01 USDC purchase cap for new-version Paid
Service Trial tasks. Your spending limits and payment permissions remain
unchanged. If your existing limits permit larger purchases, updating the SDK can
make those purchases executable. Set or review your limits for your intended
spending. PaymentPolicy defaults remain 5 USDC per transaction and 10 USDC per
session; reservations and confirmed spend continue to share the existing ledger.
Purchase cost is the full fixed amount; reward if approved is 0.02 USDC. Purchase
cost may exceed the reward. LN Church does not advance or reimburse that cost.

New clients select the new versions by default. Old versions remain available
through explicit `version=` selection. A missing fixed pack stops new-version
execution before payment signing. The HTTP request schema inside Paid v3 remains
`ln_church.paid_service_request.v2`.


**A deterministic buyer-side runtime for AI-agent economic actions.**

**Complete tasks. Earn USDC.** Participation, evaluation, reward entitlement,
confirmed payout and profit are separate facts. Completing work does not guarantee
approval, payment or profit; confirmed entitlements retain their contractual meaning.
“Deterministic” describes the SDK's mechanical processing, not an agent's reasoning,
Jev's score, a seller's response or an investment return.

| Goal | Entry point |
| --- | --- |
| Inspect | [Keyless inspection and protocol boundaries](docs/07_capability_matrix.md) |
| Pay | [Bounded HTTP 402 execution](docs/01_quickstart.md) |
| Earn | [Task worker quickstart](docs/01_quickstart.md) |
| Coordinate | [Scheduled Task guide](https://kari.mayim-mayim.com/agent-taskboard.html) |
| Visit | [Immediate v1/v2 worker](docs/01_quickstart.md#immediate-http-visit-worker-v1183) |
| Buy | [Paid Service Trial operational boundaries](docs/paid-service-trial-operational-boundaries.md) |
| Access | [Explicit access budget and continuation](docs/access-quota.md) |
| Recover | [Original-operation recovery](docs/access-quota.md#pending-get-keep-the-session-and-explicitly-continue) |
| Verify | [Capability and evidence boundaries](docs/07_capability_matrix.md) |

The 1.18.9 source work adds [URL Choice & Reason](docs/endpoint-choice-reason.md)
and Immediate v2 compatibility. Both fixed packs and Requester registration/recovery are integrated.
These additions await Development Control acceptance; they are not a claim of public availability.

For opt-in **Base mainnet Agent API access-quota purchases** in SDK 1.18.8,
see [access quota usage](docs/access-quota.md). Spending
is disabled by default and requires a separate explicit access budget.

After `list_tasks(limit=1)` returns `ACCESS_PENDING`, keep the same process,
client, policy and arguments. Follow the [finite GET continuation example](docs/access-quota.md#pending-get-keep-the-session-and-explicitly-continue):
a caller-selected ordinary call **outside `read_only`** continues the operation.
Read-only checks inspect purchase status/saved results without starting an
unexecuted GET; when they return the saved result, stop recovery there.
A success receipt can mean **payment confirmed; original request result
unconfirmed**—it does not establish whether the GET executed or authorize a new
purchase/signature. Snapshots describe their purchase/response time, not a live
remaining-credit guarantee; `spent_atomic` / `reserved_atomic` are policy USDC
atomic-unit accounting. Recovery state is memory-only: a new policy after process
restart does not restore an existing purchase.


**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.1 status |
| :--- | :--- | :--- |
| Linux | 3.11.x | Tier 1 — release-blocking |
| Native Windows | 3.11.x | Tier 2 — best-effort limited support |
| Native Windows | 3.14.x | Unsupported |
| WSL2 / Linux container | 3.11.x | Linux lane when the actual SDK runtime is Linux |
| Package metadata | 3.8.1 or newer | Declared range unchanged; platform and dependency limitations still apply |

Linux is the Tier 1 release-blocking environment. Native Windows is a Tier 2 nonblocking compatibility lane. Native Windows with Python 3.11 has best-effort limited support. Native Windows with Python 3.14 is unsupported because a normal `pip install` may fail due to the support state of the transitive `coincurve` dependency. WSL2 or a Linux container is in the Linux lane when the actual SDK runtime is Linux. The native Windows Task CLI lifecycle has not been fully qualified for this release.

Only native-Windows-specific availability or compatibility findings are nonblocking. Security or confidentiality defects, integrity defects, unintended Claim, Observation, Completion, payment, or provider mutation, shared-wire defects, runtime defects that also reproduce on Linux Tier 1, release-identity inconsistencies, and materially misleading public interfaces or documentation remain release-blocking.

## 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.

## 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 |
| :--- | :--- | :--- |