@lightninglabs/pi-402 0.0.1 → 0.0.3

package/README.md

@@ -95,6 +95,7 @@ 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
@@ -183,6 +184,7 @@ The WASM bundle is not in git. To work on the embedded wallet, build it with
 
 ## 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lightninglabs/pi-402",
-	"version": "0.0.1",
+	"version": "0.0.3",
 	"description": "Pay for Pi inference with Lightning: an L402 + walletdk extension for the Pi coding agent",
 	"type": "module",
 	"license": "MIT",

package/src/format.ts

@@ -0,0 +1,4 @@
+// formatSat groups the digits of a sat amount for display ("58,000").
+export function formatSat(sat: number): string {
+	return sat.toLocaleString("en-US");
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 import { registerReceiptCommands, registerWalletCommands } from "./commands.ts";
+import { formatSat } from "./format.ts";
 import { MockInvoicePayer, WalletInvoicePayer } from "./payer.ts";
 import { buildBudgetPolicy } from "./policy.ts";
 import { makeStreamSimple } from "./provider.ts";
@@ -23,10 +24,35 @@ export default function (pi: ExtensionAPI): void {
 	// The wallet holds the embedded walletdk instance for the whole session.
 	const wallet = new WalletService();
 
+	// The footer status shows the wallet balance, and a one-line notice marks
+	// each payment, so an agent that spends on its own never does it silently.
+	// The UI handle arrives with session_start; it is a convenience only, so a
+	// failure here (no UI, a stale session, a balance read that errors) is
+	// swallowed and never reaches a payment.
+	let ui: ExtensionUIContext | undefined;
+	const showBalance = async (paidSat?: number): Promise<void> => {
+		const target = ui;
+		if (!target) {
+			return;
+		}
+
+		try {
+			const balance = await wallet.confirmedBalanceSat();
+			target.setStatus("pi-402", `⚡ ${formatSat(balance)} sat`);
+			if (paidSat !== undefined) {
+				target.notify(`pi-402 paid ${formatSat(paidSat)} sat (${formatSat(balance)} sat left)`, "info");
+			}
+		} catch {
+			// Leave the last status in place.
+		}
+	};
+
 	// The mock payer exercises the buyer loop end to end against a mock proxy
 	// with no Lightning at all; the real payer settles through walletdk.
 	const mockMode = process.env.PI402_MOCK_PAYER === "1";
-	const payer = mockMode ? new MockInvoicePayer() : new WalletInvoicePayer(wallet);
+	const payer = mockMode
+		? new MockInvoicePayer()
+		: new WalletInvoicePayer(wallet, ({ amountPaidSat }) => showBalance(amountPaidSat));
 
 	// Durable state: paid tokens and the receipt ledger live under the data
 	// dir, so a paid bundle survives a restart instead of being re-purchased
@@ -44,8 +70,23 @@ export default function (pi: ExtensionAPI): void {
 	// Bootstrap the wallet once per session. In mock mode there is no wallet
 	// to load, so the session starts without touching the WASM at all.
 	if (!mockMode) {
-		pi.on("session_start", async () => {
+		pi.on("session_start", async (_event, ctx) => {
 			await wallet.startAndUnlock();
+			ui = ctx.ui;
+			await showBalance();
+		});
+
+		// Release the wallet when Pi tears the extension down. Without this
+		// the WASM runtime and its SQLite worker thread keep Node's event
+		// loop alive, and a non-interactive `pi -p` never exits.
+		//
+		// Only a quit stops it. Pi also emits session_shutdown when it replaces
+		// the session (reload, new, resume, fork) and keeps running, and the
+		// next session needs the wallet the SQLite bridge belongs to.
+		pi.on("session_shutdown", async (event) => {
+			if (event.reason === "quit") {
+				await wallet.stop();
+			}
 		});
 	}
 
@@ -103,6 +144,17 @@ export default function (pi: ExtensionAPI): void {
 				contextWindow: 1_048_576,
 				maxTokens: 32_768,
 			},
+			{
+				// Maps to moonshotai/Kimi-K3.1-Pro on the wire. 1M-token
+				// context, priced below Kimi K3 upstream.
+				id: "kimi-k3.1-pro",
+				name: "Kimi K3.1 Pro (L402)",
+				input: ["text"],
+				reasoning: true,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+				contextWindow: 1_000_000,
+				maxTokens: 32_768,
+			},
 		],
 		streamSimple: makeStreamSimple({ payer, policy, tokenStore, credentialStore, receiptLog }),
 	});

package/src/payer.ts

@@ -8,6 +8,9 @@ interface PayInvoiceInput {
 	challengeId: string;
 }
 
+// PaidHook is told about each payment the wallet settles.
+export type PaidHook = (paid: { amountPaidSat: number }) => void | Promise<void>;
+
 // MockInvoicePayer returns a fixed preimage without paying anything. It exists
 // so the buyer loop can be exercised end to end with no wallet and no
 // Lightning at all.
@@ -23,12 +26,26 @@ export class MockInvoicePayer implements InvoicePayer {
 // is read off the settled activity entry once the swap completes.
 export class WalletInvoicePayer implements InvoicePayer {
 	private readonly wallet: WalletService;
+	private readonly onPaid?: PaidHook;
 
-	constructor(wallet: WalletService) {
+	// onPaid runs after each successful payment, for display only: it is not
+	// awaited and a failure in it is swallowed, so it can never delay a
+	// payment's preimage or turn a settled payment into an error.
+	constructor(wallet: WalletService, onPaid?: PaidHook) {
 		this.wallet = wallet;
+		this.onPaid = onPaid;
 	}
 
 	async payInvoice(input: PayInvoiceInput): Promise<{ preimageHex: string; amountPaidSat: number }> {
-		return this.wallet.payInvoice(input.invoice, input.amountSat);
+		const result = await this.wallet.payInvoice(input.invoice, input.amountSat);
+
+		if (this.onPaid) {
+			const hook = this.onPaid;
+			void Promise.resolve()
+				.then(() => hook({ amountPaidSat: result.amountPaidSat }))
+				.catch(() => {});
+		}
+
+		return result;
 	}
 }

package/src/provider.ts

@@ -57,6 +57,7 @@ const BASETEN_MODEL_SLUGS: Record<string, string> = {
 	"glm-5": "zai-org/GLM-5",
 	"glm-5.2": "zai-org/GLM-5.2",
 	"kimi-k3": "moonshotai/Kimi-K3",
+	"kimi-k3.1-pro": "moonshotai/Kimi-K3.1-Pro",
 };
 
 // wireModelId resolves the model id sent to the proxy/upstream.

package/src/wallet.ts

@@ -104,6 +104,9 @@ export class WalletService {
 	// any more, so calls have to fail fast rather than hang against it.
 	private runtimeExited = false;
 
+	// stopped records that stop() has run, so a second call does nothing.
+	private stopped = false;
+
 	// startAndUnlock brings up the selected backend and unlocks the wallet,
 	// creating it on the first run. It is bootstrapped once per session from
 	// the session_start hook.
@@ -274,6 +277,14 @@ export class WalletService {
 		}
 	}
 
+	// Credit caps: small payments (under about 1,000 sat) go over the swap
+	// server's credit rail, and the wallet only authorizes that rail when the
+	// caller sets an explicit cap. With no cap the quote is refused ("below
+	// the 1000 sat minimum for pay swaps"), which is how a 20 sat session
+	// deposit fails. We pass the per-request ceiling for both caps, so the
+	// wallet never reserves or tops up more credit than a single request may
+	// spend.
+	//
 	// payInvoice pays a BOLT11 invoice via a two-phase wavewalletdk send.
 	// prepareSend quotes the payment (including the swap fee), send
 	// dispatches it, and the preimage is read from the settled entry once
@@ -289,7 +300,11 @@ export class WalletService {
 		const ceiling = maxSatPerRequest();
 
 		if (this.gateway) {
-			const quote = await this.rest("/v1/wallet/prepare-send", { invoice });
+			const quote = await this.rest("/v1/wallet/prepare-send", {
+				invoice,
+				max_credit_sat: ceiling,
+				max_credit_topup_sat: ceiling,
+			});
 			const outflow = quotedOutflowSat(quote);
 			assertWithinCeiling(outflow, ceiling);
 
@@ -312,7 +327,11 @@ export class WalletService {
 		}
 
 		const call = this.requireCall();
-		const quote = await call("prepareSend", { Invoice: invoice });
+		const quote = await call("prepareSend", {
+			Invoice: invoice,
+			MaxCreditSat: ceiling,
+			MaxCreditTopupSat: ceiling,
+		});
 		const outflow = quotedOutflowSat(quote);
 		assertWithinCeiling(outflow, ceiling);
 
@@ -502,6 +521,57 @@ export class WalletService {
 		return payload;
 	}
 
+	// stop shuts the embedded wallet down so the process can exit. The Go
+	// runtime parks on a channel and the SQLite bridge owns a worker thread;
+	// a worker thread is a live handle, so until both are released Node never
+	// drains its event loop and a non-interactive `pi -p` hangs after the
+	// reply is printed.
+	//
+	// It is idempotent, a no-op when the embedded runtime never started (mock
+	// mode, sidecar mode, or a failed bootstrap), and never throws: it runs on
+	// Pi's shutdown path, where an error would only mask the exit. Each step
+	// is bounded by timeoutMs so a wedged wallet cannot hang the exit it is
+	// meant to enable.
+	async stop(timeoutMs = 5_000): Promise<void> {
+		const call = this.call;
+		if (!call || this.stopped) {
+			return;
+		}
+		this.stopped = true;
+
+		// Once stopping begins nothing may use the wallet again.
+		this.ready = false;
+
+		const bounded = async (what: string, work: () => Promise<unknown>) => {
+			let timer: NodeJS.Timeout | undefined;
+			try {
+				await Promise.race([
+					work(),
+					new Promise((_, reject) => {
+						timer = setTimeout(() => reject(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
+					}),
+				]);
+			} catch (err) {
+				console.error(`[pi-402] embedded wallet ${what} failed:`, err);
+			} finally {
+				clearTimeout(timer);
+			}
+		};
+
+		// If the runtime already died on its own there is nothing to stop,
+		// but the worker thread may still be holding the process open.
+		if (!this.runtimeExited) {
+			await bounded("stop", () => call("stop"));
+		}
+
+		// The bridge's shutdown terminates the SQLite worker. It runs even
+		// when stop failed, since a leaked worker is what blocks the exit.
+		const bridge = (globalThis as any).sqliteBridge;
+		if (typeof bridge?.shutdown === "function") {
+			await bounded("sqlite shutdown", () => bridge.shutdown());
+		}
+	}
+
 	// noteRuntimeExit records that the embedded Go runtime is gone. The
 	// program is supposed to run for the lifetime of the process, so any exit
 	// is the wallet dying, and the only useful things to do are say so once,

package/wasm/wavewalletdk.wasm

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/wasm/wavewalletdk.wasm
-size: 136699930 bytes
-sha256: eac3751112c824328c2d62224453e34b18ef94c5459b897e44718d881e8353ac
+size: 133563673 bytes
+sha256: 6d945797ce051806ed880b80a22a3a79e2b303d229cea41dc6d5071a30139f84