@lightninglabs/pi-402 0.0.0-stage → 0.0.2

package/INSTALL.md

@@ -0,0 +1,270 @@
+# Installing pi-402
+
+`pi-402` is a standard [Pi](https://pi.dev) extension. Pi can load an extension
+from a managed package, from an auto-discovered directory, or from a per-run
+flag, and pi-402 works with all three. Pi itself is not patched or forked. We
+have verified the install paths below against Pi 1.1.0.
+
+## Prerequisites
+
+You need Pi (`pi --version`) and Node.js 22.19 or newer. That is all for the
+install. To make a payment you also need two things that pi-402 does not
+provide:
+
+- An L402 proxy that fronts a model, reachable at the URL you put in
+  `L402_PROXY_URL`. There is no hosted endpoint, so you run one yourself or use
+  one run by a provider. See [Bring your own seller](#bring-your-own-seller).
+- A funded wallet. The wallet is built in and creates itself on first use, and
+  you fund it with `/fund` once Pi is running. See [Wallet](#wallet).
+
+## Option 1: pi install from npm (recommended)
+
+Pi's package manager downloads the package, records it in your settings, and
+loads it on every run. The package carries the embedded wallet's WASM bundle
+(about 137 MB unpacked, 22 MB to download), so nothing else needs building.
+
+```bash
+# Global (user scope, ~/.pi/agent): available in every project.
+pi install npm:@lightninglabs/pi-402
+
+# Project scope only (recorded in ./.pi):
+pi install npm:@lightninglabs/pi-402 -l
+```
+
+The package declares its entry point in `package.json`, so Pi finds the
+extension without any further wiring:
+
+```json
+"pi": { "extensions": ["./src/index.ts"] }
+```
+
+To update or remove it later:
+
+```bash
+pi update --extensions
+pi remove npm:@lightninglabs/pi-402     # alias: pi uninstall
+```
+
+### Installing from git instead
+
+```bash
+pi install git:github.com/lightninglabs/pi-402
+```
+
+A git checkout does not contain the wallet's WASM bundle. It is about 137 MB, so
+it ships in the npm package and not in the repository. After a git install, stage
+a bundle built from [Wavelength](https://github.com/lightninglabs/wavelength)
+(`make wasm-wallet` writes it to `bin/wasm`) into the package, or point
+`PI402_WASM_DIR` at it:
+
+```bash
+scripts/stage-wasm.sh /path/to/wavelength/bin/wasm   # copies into ./wasm
+# or, without copying anything:
+export PI402_WASM_DIR=/path/to/wavelength/bin/wasm
+```
+
+## Option 2: auto-discovered directory
+
+Pi scans two directories on startup and loads any extension it finds there:
+
+```bash
+# Global: every project.
+git clone https://github.com/lightninglabs/pi-402.git ~/.pi/agent/extensions/pi-402
+
+# Project-local: only when Pi runs in this project.
+git clone https://github.com/lightninglabs/pi-402.git ./.pi/extensions/pi-402
+```
+
+Install its dependencies once with `npm install` inside the clone, and stage the
+WASM bundle as described above.
+
+## Option 3: per-run flag
+
+Point Pi at a checkout for a single session, which is the usual way to develop
+the extension:
+
+```bash
+pi -e /path/to/pi-402          # -e is short for --extension
+```
+
+## Where Pi looks for extensions
+
+| Location | Scope | How it gets there |
+|---|---|---|
+| `./.pi/extensions/` | Project | Option 2 (project) |
+| `~/.pi/agent/extensions/` | Global | Option 2 (global) |
+| Recorded packages in settings | Project or global | `pi install` (Option 1) |
+| `--extension <path>` / `-e <path>` | This run only | Option 3 |
+
+The agent directory is overridable via `PI_CODING_AGENT_DIR`.
+
+## Bring your own seller
+
+pi-402 is the buyer. The seller is an [aperture](https://github.com/lightninglabs/aperture)
+proxy that fronts an OpenAI-compatible model endpoint, answers an unpaid request
+with a `402` challenge carrying a Lightning invoice, and meters the paid bundle
+as the model serves tokens. Aperture's
+[`docs/metering.md`](https://github.com/lightninglabs/aperture/blob/master/docs/metering.md)
+describes how that works, and
+[lightmeter](https://github.com/lightninglabs/lightmeter) is the metering
+controller that prices bundles. If you want to run the seller on your own
+machine to try pi-402, `dev/regtest/README.md` and `dev/signet-demo.md` walk
+through a complete stack.
+
+Whoever runs the seller, you point pi-402 at it with one variable:
+
+```bash
+export L402_PROXY_URL="https://your-aperture.example/v1"
+```
+
+The URL is the base that the OpenAI client appends `/chat/completions` to, so it
+includes the API prefix (`/v1` for aperture). If it is unset, pi-402 uses
+`http://localhost:8402`. The proxy holds the model credential. Pi never sees an
+API key.
+
+## Wallet
+
+The wallet is Wavelength's, running inside the Pi process as WASM. There is no
+daemon to start. On the first session it creates itself under
+`~/.pi402/wallet` (override with `PI402_WALLET_DIR`) and writes its seed words
+to `seed.txt` there, readable only by you. Back that file up. It is the only
+copy, and the wallet cannot be recovered without it.
+
+A running native `waved` can be used instead of the embedded wallet. Set
+`PI402_WALLETD_GATEWAY` to its HTTP/JSON gateway (for example
+`http://localhost:10031`) and pi-402 drives that daemon and loads no WASM.
+
+### Choosing a network
+
+`PI402_NETWORK` selects the network and defaults to `regtest`, which is for the
+local dev stack. For anything real, set it explicitly. On `signet` and the
+other test networks the embedded daemon finds the hosted Ark operator, swap
+server and chain endpoints by itself. Only `regtest` needs them given, and it
+defaults to the local compose stack's addresses; `PI402_ARK_SERVER`,
+`PI402_SWAP_SERVER` and `PI402_ESPLORA_URL` override them on any network.
+
+On non-mainnet networks the wallet uses a throwaway default password and
+generates a seed without asking. Mainnet is stricter, because the funds are real:
+
+- `PI402_WALLET_PASSWORD` must be set to a secret of your own. The extension
+  refuses to start a mainnet wallet with the built-in default.
+- A fresh mainnet wallet will not generate a seed that would be written to disk
+  in the clear. Either restore a seed you already hold by setting
+  `PI402_WALLET_MNEMONIC` to its words, or set `PI402_ALLOW_PLAINTEXT_SEED=1` to
+  accept a plaintext `seed.txt` beside the wallet database.
+- If `seed.txt` is present but the wallet database is gone, creation is refused
+  so the old words are never mistaken for the new wallet's backup. Restore from
+  the words with `PI402_WALLET_MNEMONIC`, or move the file away to start fresh.
+
+### Funding
+
+Inside Pi:
+
+```
+/fund 50000     a Lightning invoice; pay it from the Wavelength app
+/deposit        an on-chain boarding address
+/balance        confirmed and pending balance
+/wallet         wallet status, and the balance in the status line
+/receipts       every payment made: count, all-time sats, and today's sats
+```
+
+`/fund` is the quick path, since an invoice settles through a swap in seconds
+while an on-chain deposit needs a confirmation and an Ark round. Whatever you
+fund is the most the agent can ever spend.
+
+## Configure and use
+
+```bash
+export L402_PROXY_URL="https://your-aperture.example/v1"
+export PI402_NETWORK=signet
+export PI402_MAX_SAT_PER_REQUEST=20000    # see the note below
+export PI402_DAILY_CAP_SAT=100000
+
+pi
+# then, inside Pi:
+/model l402-baseten/kimi-k3
+```
+
+The per-request ceiling defaults to 1000 sats and is checked against the quoted
+total outflow, meaning the invoice plus the swap fee. A seller that sells a
+large token bundle in one invoice can quote more than that, and then the budget
+policy declines the payment. Set the ceiling above the bundle price you expect.
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `L402_PROXY_URL` | `http://localhost:8402` | Base URL of the L402 proxy, including the API prefix |
+| `PI402_MAX_SAT_PER_REQUEST` | `1000` | Per-request spend ceiling, checked on the quoted total outflow |
+| `PI402_DAILY_CAP_SAT` | `100000` | Daily spend ceiling, seeded from the receipt ledger on restart |
+| `PI402_PAYMENT_SCHEME` | `auto` | `auto` takes a Payment offer when the seller makes one and falls back to L402; `l402` pins L402 |
+| `PI402_MPP_INTENTS` | `charge` | Payment intents to accept. `session` is refused, since the swap-backed wallet cannot mint the refund invoice it needs |
+| `PI402_NETWORK` | `regtest` | Network the embedded wallet runs on (`signet`, `mainnet`, and so on) |
+| `PI402_WALLET_PASSWORD` | dev default | Wallet password; required on mainnet |
+| `PI402_WALLET_MNEMONIC` | unset | Seed words to restore on first run instead of generating a wallet |
+| `PI402_ALLOW_PLAINTEXT_SEED` | unset | Set to `1` to let a new mainnet wallet write a plaintext `seed.txt` |
+| `PI402_WALLET_DIR` | `$PI402_DATA_DIR/wallet` | Where the embedded wallet keeps its databases and `seed.txt` |
+| `PI402_DATA_DIR` | `~/.pi402` | Token cache, credential cache, receipt ledger and wallet |
+| `PI402_WASM_DIR` | `<package>/wasm` | Directory holding the WASM bundle, overriding the bundled copy |
+| `PI402_WALLETD_GATEWAY` | unset | Use a native `waved` at this gateway URL instead of the embedded wallet |
+| `PI402_ARK_SERVER` | regtest: `127.0.0.1:7070` | Ark operator address; other networks resolve it by name |
+| `PI402_SWAP_SERVER` | regtest: `127.0.0.1:8082` | Swap server address; other networks resolve it by name |
+| `PI402_ESPLORA_URL` | regtest: `http://127.0.0.1:3002` | Esplora API; other networks resolve it by name |
+| `PI402_SERVER_INSECURE` | `1` on regtest, else `0` | Plaintext transport to the operator and swap server |
+| `PI402_DEBUG_LEVEL` | `error` | Embedded daemon log level (`debug`, `trace`, or `info,ROND=debug`) |
+| `PI402_MOCK_PAYER` | unset | Set to `1` to skip Lightning and "pay" with a mock, against a mock proxy |
+
+The embedded daemon logs through the Pi process, so it logs errors only by
+default to keep its output off the TUI. Raise `PI402_DEBUG_LEVEL` when a swap
+sticks.
+
+## Trying it without a seller
+
+`PI402_MOCK_PAYER=1` runs the buyer loop with no wallet and no Lightning, against
+any mock L402 proxy such as `dev/mock-l402-proxy.ts`:
+
+```bash
+export PI402_MOCK_PAYER=1
+export L402_PROXY_URL="http://localhost:8402"
+pi -e /path/to/pi-402
+```
+
+## Developing against a local aperture-ts checkout
+
+The buyer loop comes from `@lightninglabs/aperture-client` and
+`@lightninglabs/aperture-core`, which `npm install` fetches from npm. To work
+against an unreleased [aperture-ts](https://github.com/lightninglabs/aperture-ts)
+instead, build it and link the two packages into your checkout:
+
+```bash
+cd aperture-ts && pnpm install && pnpm -r build
+cd ../pi-402 && npm install --legacy-peer-deps
+mkdir -p node_modules/@lightninglabs
+ln -sfn ../../../aperture-ts/packages/core   node_modules/@lightninglabs/aperture-core
+ln -sfn ../../../aperture-ts/packages/client node_modules/@lightninglabs/aperture-client
+```
+
+The Pi packages (`@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`) are
+peers. Pi provides them when it loads the extension, but `npm run check` needs
+them installed in the checkout.
+
+## Troubleshooting
+
+```bash
+pi -ne              # start with no extensions, to isolate a load failure
+```
+
+If the extension fails to load, Pi prints `Failed to load extension "<path>"`
+and the paid models never appear. The usual cause:
+
+- `Cannot find module '@lightninglabs/aperture-client'`: dependencies are not
+  installed. Reinstall from npm, or run `npm install` in a checkout.
+
+If the extension loads but the wallet cannot start, Pi keeps running and prints
+`Extension "<path>" error: ...` at session start. The usual causes:
+
+- `wasm bundle at ... is missing ...`: the bundle is incomplete or absent. Stage
+  one with `scripts/stage-wasm.sh`, or set `PI402_WASM_DIR`.
+- `wasm bundle at ... would load as ES modules`: the bundle sits inside a
+  `"type": "module"` package without a `package.json` of its own. Re-run
+  `scripts/stage-wasm.sh`, or add a `package.json` containing
+  `{"type":"commonjs"}` to the bundle directory.
+- A payment declined with a budget error: raise `PI402_MAX_SAT_PER_REQUEST`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lightning Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,193 @@
-# Temporary Holding Version
+<p align="center">
+  <a href="https://pi.dev">
+    <img alt="pi logo" src="https://pi.dev/logo-auto.svg" width="128">
+  </a>
+</p>
+<p align="center">
+  <strong>pi-402</strong>: pay for inference with Lightning
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# pi-402
+
+`pi-402` is a [Pi](https://pi.dev) extension that pays for LLM inference over
+Lightning. It loads an embedded
+[Wavelength](https://github.com/lightninglabs/wavelength) wallet, registers a
+paid model provider, and settles each inference call against an
+[aperture](https://github.com/lightninglabs/aperture) proxy, so you can run Pi
+against a metered model with sats instead of an API key.
+
+No changes to Pi itself: this is a self-contained extension you drop into your
+own Pi install.
+
+Inference is priced by the token rather than by the request. One payment buys a
+bundle of tokens, and the proxy debits what the model actually reported serving,
+weighted by direction, until the bundle runs out and a fresh challenge arrives.
+See [`docs/metering.md`](https://github.com/lightninglabs/aperture/blob/master/docs/metering.md)
+in aperture for how that works end to end.
+
+## How it works
+
+```
+Pi  ──▶  pi-402 provider  ──▶  OpenAI client (fetch = payingFetch)  ──▶  aperture  ──▶  Baseten
+                │                         │ 402 → pay → retry                │
+                └── Wavelength wallet ◀───┘ pays the BOLT11 invoice          └── holds the model key
+                    (Ark↔Lightning swap)
+```
+
+The extension registers a provider whose `streamSimple` owns the request path,
+wrapping the model call in a paying `fetch`. When the proxy answers `402`, the
+buyer loop runs your budget policy, pays the invoice through the embedded
+wallet, caches the credential, and retries. Streaming included, and the agent
+loop above it never learns that a payment happened.
+
+The proxy offers two doors on the same `402` and the buyer takes whichever it
+speaks: **L402** (a macaroon bound to the invoice's payment hash, which you can
+attenuate offline and hand to a sub-agent) and the **Payment HTTP
+Authentication Scheme** (`draft-httpauth-payment-00`, the IETF draft co-authored
+by Stripe and Tempo). `PI402_PAYMENT_SCHEME` picks; the default takes a Payment
+offer when the seller makes one and falls back to L402.
+
+No API key ever reaches the buyer. Aperture holds the model credential and
+injects it server-side, so the buyer holds sats and the seller holds the key.
+
+## Install
+
+```bash
+pi install npm:@lightninglabs/pi-402
+```
+
+Pi's package manager downloads the package and loads it on every run. The
+package carries the embedded wallet's WASM bundle, so there is nothing to build
+and no daemon to start. You need Node.js 22.19 or newer, and we have verified it
+against Pi 1.1.0. [INSTALL.md](INSTALL.md) covers the alternatives (a git
+install, an auto-discovered directory, and `pi -e` for development) and
+troubleshooting.
+
+pi-402 is the buyer half. It pays a seller, and there is no hosted seller to
+point it at yet, so you bring your own.
+
+## Bring your own seller
+
+The seller is an [aperture](https://github.com/lightninglabs/aperture) proxy in
+front of an OpenAI-compatible model endpoint, with metering turned on so a
+payment buys a bundle of tokens that is drawn down as the model serves them.
+Aperture's
+[`docs/metering.md`](https://github.com/lightninglabs/aperture/blob/master/docs/metering.md)
+explains the mechanism, and [lightmeter](https://github.com/lightninglabs/lightmeter)
+is the controller that prices the bundles. Run your own, or use one a provider
+runs, and point pi-402 at it:
+
+```bash
+export L402_PROXY_URL="https://your-aperture.example/v1"   # include the /v1
+export PI402_NETWORK=signet                                 # defaults to regtest
+export PI402_MAX_SAT_PER_REQUEST=20000                      # above the bundle price
+```
+
+The per-request ceiling defaults to 1000 sats and is checked against the quoted
+total outflow, so raise it above whatever your seller's bundle costs or the
+budget policy will decline the payment. `dev/regtest/README.md` and
+`dev/signet-demo.md` bring up a complete seller and buyer on one machine, which
+is the way to try pi-402 end to end.
+
+## Use
+
+Select a paid model and prompt:
+
+```
+/model l402-baseten/kimi-k3           # 1M context, natively multimodal
+/model l402-baseten/kimi-k3.1-pro     # 1M context, cheaper than K3 upstream
+/model l402-baseten/glm-4.7           # 200K context
+/model l402-baseten/glm-5.2           # 200K context
+/model l402-baseten/deepseek-v4-flash # 1M context, the cheap one
+```
+
+These are the models the extension registers. What a given seller actually serves
+is up to the seller.
+
+Wallet commands:
+
+```
+/wallet        show wallet status and balance
+/fund <sats>   show a Lightning invoice to fund the wallet (settles in seconds)
+/deposit       show an on-chain boarding address to fund the wallet
+/balance       show confirmed balance
+/receipts      show the payment ledger: count, all-time and today's sats
+```
+
+`/fund` is the path to use. It mints a BOLT11 invoice that you pay from the
+[Wavelength](https://wavelength.money) app on your phone, and the sats land in
+seconds through an inbound swap. The wallet is an Ark wallet, so there are no
+channels to open, no inbound liquidity to source, and nothing to keep online.
+
+Whatever you fund is the ceiling on what the agent can ever spend, which is a
+more comfortable thing to hand an autonomous process than a card.
+
+## The wallet
+
+The wallet runs inside the Pi process as WASM, shipped in the package. On the
+first session it creates itself under `~/.pi402/wallet` and writes its seed
+words to `seed.txt` there. Back that file up: it is the only copy.
+
+On mainnet we are stricter, because the funds are real. `PI402_WALLET_PASSWORD`
+must be set to a secret of your own, and a new wallet will not write a plaintext
+seed unless you either restore words you already hold with
+`PI402_WALLET_MNEMONIC` or accept the plaintext file with
+`PI402_ALLOW_PLAINTEXT_SEED=1`.
+
+Two overrides exist. `PI402_WASM_DIR` points at a different WASM bundle than the
+bundled one, for example a fresh build from Wavelength. `PI402_WALLETD_GATEWAY`
+points at a native `waved` that is already running, and pi-402 then drives that
+daemon and loads no WASM.
+
+## Configuration
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `L402_PROXY_URL` | `http://localhost:8402` | Base URL of the L402 proxy fronting the model, including the API prefix (for aperture, `/v1`) |
+| `PI402_MAX_SAT_PER_REQUEST` | `1000` | Per-request spend ceiling, checked on the quoted total outflow |
+| `PI402_DAILY_CAP_SAT` | `100000` | Daily spend ceiling, seeded from the receipt ledger on restart |
+| `PI402_PAYMENT_SCHEME` | `auto` | `auto` takes a Payment offer when the seller makes one, else L402; `l402` forces the L402 door |
+| `PI402_MPP_INTENTS` | `charge` | Comma-separated Payment intents to accept. Sessions need a return-invoice minter, which the swap-backed wallet cannot supply yet, so asking for `session` here throws. |
+| `PI402_NETWORK` | `regtest` | Network the wallet runs on, for example `signet` or `mainnet` |
+| `PI402_WALLET_PASSWORD` | dev default | Wallet password; mainnet refuses the default |
+| `PI402_WALLET_MNEMONIC` | unset | Seed words to restore on first run instead of generating a wallet |
+| `PI402_ALLOW_PLAINTEXT_SEED` | unset | `1` lets a new mainnet wallet write a plaintext `seed.txt` |
+| `PI402_WALLET_DIR` | `$PI402_DATA_DIR/wallet` | Wallet databases and `seed.txt` |
+| `PI402_DATA_DIR` | `~/.pi402` | Token cache, credential cache, receipt ledger, and the wallet |
+| `PI402_WASM_DIR` | `<package>/wasm` | WASM bundle directory, overriding the bundled copy |
+| `PI402_WALLETD_GATEWAY` | unset | Use a native `waved` at this HTTP/JSON gateway (e.g. `http://localhost:10031`) instead of the embedded wallet |
+| `PI402_ARK_SERVER` | regtest only | Ark operator address; other networks resolve it by name |
+| `PI402_SWAP_SERVER` | regtest only | Swap server address; other networks resolve it by name |
+| `PI402_ESPLORA_URL` | regtest only | Esplora API; other networks resolve it by name |
+| `PI402_SERVER_INSECURE` | `1` on regtest, else `0` | Plaintext transport to the operator and swap server |
+| `PI402_DEBUG_LEVEL` | `error` | Embedded daemon log level. Quiet by default so it stays off the TUI; raise it (`debug`, or `info,ROND=debug`) when a swap sticks |
+| `PI402_MOCK_PAYER` | unset | `1` uses the mock payer (no Lightning; dev only) |
+
+## Development
+
+This repo is also the dev environment for the extension.
+
+```bash
+npm install --legacy-peer-deps
+npm run check   # biome + tsc
+npm test
+```
+
+The buyer loop reuses [`@lightninglabs/aperture-client`](https://github.com/lightninglabs/aperture-ts)
+(`createPayingFetch`) and [`@lightninglabs/aperture-core`](https://github.com/lightninglabs/aperture-ts)
+(`InvoicePayer`, budget policies), both from npm. INSTALL.md has a note on linking
+a local aperture-ts checkout instead.
+
+The WASM bundle is not in git. To work on the embedded wallet, build it with
+`make wasm-wallet` in Wavelength and run `scripts/stage-wasm.sh <path-to-bin/wasm>`.
+`npm publish` refuses to run unless that staged bundle is complete.
+
+## Docs
+
+- [`docs/architecture.md`](docs/architecture.md): a map of the extension: components, request and payment pipelines, storage, and concurrency.
+- [`docs/l402-walletdk-inference-payments.md`](docs/l402-walletdk-inference-payments.md): end-to-end design of the extension.
+- [`docs/l402-protocol-extensions.md`](docs/l402-protocol-extensions.md): furthering L402 for metered / streaming inference: keep the macaroon + preimage atomic core, add the session economic model (verifiable receipts, HTLC-native refunds, a BOLT12 payment plane), informed by the Machine Payment Protocol.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,48 @@
 {
-  "name": "@lightninglabs/pi-402",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@lightninglabs/pi-402",
+	"version": "0.0.2",
+	"description": "Pay for Pi inference with Lightning: an L402 + walletdk extension for the Pi coding agent",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/lightninglabs/pi-402.git"
+	},
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"files": [
+		"src",
+		"wasm",
+		"README.md",
+		"INSTALL.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"stage-wasm": "scripts/stage-wasm.sh",
+		"prepublishOnly": "scripts/stage-wasm.sh --verify",
+		"check": "biome check --write --error-on-warnings . && tsc --noEmit",
+		"test": "node --test 'test/**/*.test.ts'",
+		"format": "biome format --write .",
+		"clean": "echo 'nothing to clean'"
+	},
+	"dependencies": {
+		"@lightninglabs/aperture-client": "~0.0.1",
+		"@lightninglabs/aperture-core": "~0.0.1",
+		"openai": "6.26.0"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.3.5",
+		"@types/node": "22.19.19",
+		"typescript": "5.9.3"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	}
+}

package/src/CLAUDE.md

@@ -0,0 +1,57 @@
+# pi-402/src
+
+## Purpose
+
+The pi-402 extension itself: the code Pi loads to register a paid, L402-settled
+model provider backed by an embedded Wavelength wallet.
+
+## Module Structure
+
+- `index.ts` — extension entry (`export default function (pi)`): registers the
+  provider, bootstraps the wallet on `session_start`, and wires the wallet
+  commands.
+- `provider.ts` — `makeStreamSimple`: the provider's `streamSimple`. Builds an
+  OpenAI client whose `fetch` is `createPayingFetch(...)` and translates the
+  OpenAI SSE stream into Pi's `AssistantMessageEventStream`, text, reasoning
+  and tool calls alike (`BlockWriter`). This is the seam that injects payment
+  without touching Pi core.
+- `payer.ts` — `InvoicePayer` implementations: `MockInvoicePayer` (dev) and
+  `WalletInvoicePayer` (delegates to `WalletService`).
+- `wallet.ts` — `WalletService`: the embedded Wavelength WASM wrapper
+  (`prepareSend` → `sendPrepared` → await preimage; balance; boarding address).
+- `policy.ts` — `buildBudgetPolicy`: per-request and daily spend ceilings; the
+  daily counter seeds from the receipt ledger on first assertion.
+- `store.ts` — durable state under `PI402_DATA_DIR` (default `~/.pi402`):
+  `FileTokenStore` (paid L402 tokens, atomic rewrite, 0600) and
+  `FileReceiptLog` (append-only NDJSON spend ledger).
+- `commands.ts` — `/wallet`, `/fund`, `/deposit`, `/balance`, `/receipts`. Two
+  funding paths: `/fund <sats>` returns a BOLT11 invoice (wallet `receive`,
+  settled through an inbound swap in seconds), `/deposit` returns an on-chain
+  boarding address (a confirmation plus an Ark round before it is spendable).
+
+## Invariants
+
+- `streamSimple` owns the whole request path; payment is injected here, nowhere
+  in Pi core. The OpenAI client sets `maxRetries: 0` so the paying fetch owns
+  retry semantics and the SDK never re-enters it to double-pay.
+- The token cache is per provider instance and file-backed outside mock mode,
+  so paid tokens are reused until expiry, across process restarts, and retries
+  never re-pay. Every settled payment appends a self-verifying receipt
+  (`sha256(preimage) == payment_hash`) to the ledger; mock-mode spends never
+  touch either file.
+- The budget policy runs before any wallet action, and the wallet re-asserts the
+  per-request ceiling on the *quoted total outflow* (invoice principal plus swap
+  fee) after `prepareSend`, before dispatching `send`/`sendPrepared`.
+
+## Status / TODO
+
+- `provider.ts` streams text, reasoning and tool calls. Declaring Pi's tools on
+  the request is not optional: Pi's system prompt tells the model it has tools
+  either way, so a request that omits them leaves a model like Kimi K3 emitting
+  its own native tool-call syntax as ordinary assistant text. Images on the
+  input side are still unmapped.
+- `wallet.ts` implements both backends: the sidecar HTTP/JSON gateway
+  (`PI402_WALLETD_GATEWAY`) and the embedded WASM bridge. Both run
+  `prepareSend` → open settle stream → `send`/`sendPrepared` → read preimage,
+  which arrives on the settled entry, so the real payer path is live.
+- Run with `PI402_MOCK_PAYER=1` to exercise the loop without spending sats.