@lightninglabs/pi-402 0.0.0-stage → 0.0.2

package/src/commands.ts

@@ -0,0 +1,104 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { type FileReceiptLog, receiptPaidSat } from "./store.ts";
+import type { WalletService } from "./wallet.ts";
+
+// registerWalletCommands wires the /wallet, /deposit, and /balance slash
+// commands. They surface the wallet's funding state to the user, out of band
+// from the inference path — the agent core never sees a boarding address.
+export function registerWalletCommands(pi: ExtensionAPI, wallet: WalletService): void {
+	pi.registerCommand("wallet", {
+		description: "Show the pi-402 wallet status and balance",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			const balance = await wallet.confirmedBalanceSat();
+			ctx.ui.setStatus("pi-402", `⚡ ${balance} sat`);
+			ctx.ui.notify(`pi-402 wallet: ${balance} sat confirmed`, "info");
+		},
+	});
+
+	pi.registerCommand("deposit", {
+		description: "Show an on-chain boarding address to fund the wallet",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			const address = await wallet.depositAddress();
+			ctx.ui.notify(`Fund your pi-402 wallet by sending on-chain funds to: ${address}`, "info");
+		},
+	});
+
+	pi.registerCommand("fund", {
+		description: "Show a Lightning invoice to fund the wallet (/fund <sats>)",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			// An on-chain deposit needs a confirmation plus an Ark round before
+			// it is spendable; an invoice receive settles through a swap in
+			// seconds, so this is the path worth reaching for when funding
+			// interactively.
+			const amountSat = parseFundAmount(args);
+			if (amountSat === null) {
+				ctx.ui.notify("Usage: /fund <sats>, for example /fund 50000", "error");
+				return;
+			}
+
+			const invoice = await wallet.receiveInvoice(amountSat);
+			ctx.ui.notify(`Pay this invoice to add ${amountSat} sat to your pi-402 wallet:\n\n${invoice}`, "info");
+		},
+	});
+
+	pi.registerCommand("balance", {
+		description: "Show the confirmed wallet balance",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			const balance = await wallet.confirmedBalanceSat();
+			ctx.ui.notify(`Confirmed balance: ${balance} sat`, "info");
+		},
+	});
+}
+
+// parseFundAmount reads the sat amount off a /fund invocation, returning null
+// when it is missing or not a positive whole number. Underscores and commas are
+// tolerated, since a funding amount is exactly the kind of number people group
+// the digits of.
+export function parseFundAmount(args: string): number | null {
+	const raw = args.trim().replace(/[_,]/g, "");
+	if (!/^\d+$/.test(raw)) {
+		return null;
+	}
+
+	const amountSat = Number(raw);
+	return Number.isSafeInteger(amountSat) && amountSat > 0 ? amountSat : null;
+}
+
+// registerReceiptCommands wires the /receipts slash command over the durable
+// payment ledger: today's spend, the all-time total, and the most recent
+// payments with their proof-of-payment hashes.
+export function registerReceiptCommands(pi: ExtensionAPI, receiptLog: FileReceiptLog): void {
+	pi.registerCommand("receipts", {
+		description: "Show L402 payment receipts and spend totals",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			const receipts = await receiptLog.readAll();
+			if (receipts.length === 0) {
+				ctx.ui.notify("No payments recorded yet.", "info");
+				return;
+			}
+
+			// One read serves all three views; the day total filters the
+			// records already in hand.
+			const day = new Date().toISOString().slice(0, 10);
+			const totalSat = receipts.reduce((sum, r) => sum + receiptPaidSat(r), 0);
+			const todaySat = receipts
+				.filter((r) => r.timestamp?.slice(0, 10) === day)
+				.reduce((sum, r) => sum + receiptPaidSat(r), 0);
+
+			const recent = receipts
+				.slice(-10)
+				.reverse()
+				.map((r) => {
+					const model = r.model ?? "unknown-model";
+					const when = r.timestamp?.replace("T", " ").slice(0, 19) ?? "unknown-time";
+					return `${when}  ${receiptPaidSat(r)} sat  ${model}  ${r.paymentHash.slice(0, 12)}…`;
+				})
+				.join("\n");
+
+			ctx.ui.notify(
+				`pi-402 receipts: ${receipts.length} payment(s), ${totalSat} sat all-time, ${todaySat} sat today\n${recent}`,
+				"info",
+			);
+		},
+	});
+}

package/src/index.ts

@@ -0,0 +1,138 @@
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerReceiptCommands, registerWalletCommands } from "./commands.ts";
+import { MockInvoicePayer, WalletInvoicePayer } from "./payer.ts";
+import { buildBudgetPolicy } from "./policy.ts";
+import { makeStreamSimple } from "./provider.ts";
+import { dataDir, FileCredentialStore, FileReceiptLog, FileTokenStore } from "./store.ts";
+import { WalletService } from "./wallet.ts";
+
+// PROVIDER_ID is the model provider this extension registers. Users select it
+// with `/model l402-baseten/<model>`.
+const PROVIDER_ID = "l402-baseten";
+
+// DEFAULT_PROXY_URL is the local L402 proxy used when L402_PROXY_URL is unset.
+const DEFAULT_PROXY_URL = "http://localhost:8402";
+
+// The extension entry point. Pi calls this with the ExtensionAPI when the
+// extension is loaded. Everything the extension does is registered here; Pi core
+// is never modified.
+export default function (pi: ExtensionAPI): void {
+	const proxyUrl = process.env.L402_PROXY_URL ?? DEFAULT_PROXY_URL;
+
+	// The wallet holds the embedded walletdk instance for the whole session.
+	const wallet = new WalletService();
+
+	// 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);
+
+	// 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
+	// and every spend leaves an auditable record. Mock mode stays in-memory,
+	// keeping fake spends out of the real ledger.
+	const stateDir = dataDir();
+	const tokenStore = mockMode ? undefined : new FileTokenStore(join(stateDir, "tokens.json"));
+	const credentialStore = mockMode ? undefined : new FileCredentialStore(join(stateDir, "credentials.json"));
+	const receiptLog = mockMode ? undefined : new FileReceiptLog(join(stateDir, "receipts.ndjson"));
+
+	// The daily cap is seeded from the ledger, so a restart mid-day cannot
+	// reset the day's spend to zero.
+	const policy = buildBudgetPolicy(pi, receiptLog);
+
+	// 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 () => {
+			await wallet.startAndUnlock();
+		});
+
+		// 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();
+			}
+		});
+	}
+
+	// Register the paid model provider. Its streamSimple owns the request path,
+	// so the paying fetch is injected without any change to Pi core.
+	pi.registerProvider(PROVIDER_ID, {
+		api: "l402-openai",
+		baseUrl: proxyUrl,
+		// The proxy holds the real model credential; Pi sends no API key.
+		apiKey: "unused",
+		models: [
+			{
+				// Maps to deepseek-ai/DeepSeek-V4-Flash-0731 on the wire.
+				// The budget option: its bundle quotes at roughly half a
+				// GLM-4.7 bundle, so it is also the cheapest way to
+				// exercise the paid path end to end.
+				id: "deepseek-v4-flash",
+				name: "DeepSeek V4 Flash (L402)",
+				input: ["text"],
+				reasoning: true,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+				contextWindow: 1_000_000,
+				maxTokens: 32_768,
+			},
+			{
+				// The Pi-facing id is slash-free; the provider maps it to
+				// the Baseten Model APIs slug (zai-org/GLM-4.7) on the wire.
+				id: "glm-4.7",
+				name: "GLM 4.7 (L402)",
+				input: ["text"],
+				reasoning: true,
+				// Cost is metered in sats at the proxy, not billed per token here.
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+				contextWindow: 200_000,
+				maxTokens: 8_192,
+			},
+			{
+				// Maps to zai-org/GLM-5.2 on the wire.
+				id: "glm-5.2",
+				name: "GLM 5.2 (L402)",
+				input: ["text"],
+				reasoning: true,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+				contextWindow: 200_000,
+				maxTokens: 8_192,
+			},
+			{
+				// Maps to moonshotai/Kimi-K3 on the wire. Natively
+				// multimodal with a 1M-token context.
+				id: "kimi-k3",
+				name: "Kimi K3 (L402)",
+				input: ["text", "image"],
+				reasoning: true,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+				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 }),
+	});
+
+	registerWalletCommands(pi, wallet);
+	if (receiptLog) {
+		registerReceiptCommands(pi, receiptLog);
+	}
+}

package/src/payer.ts

@@ -0,0 +1,34 @@
+import type { InvoicePayer } from "@lightninglabs/aperture-core";
+import type { WalletService } from "./wallet.ts";
+
+// PayInvoiceInput is the L402 buyer loop's request to pay a challenge invoice.
+interface PayInvoiceInput {
+	invoice: string;
+	amountSat: number;
+	challengeId: string;
+}
+
+// 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.
+export class MockInvoicePayer implements InvoicePayer {
+	async payInvoice(input: PayInvoiceInput): Promise<{ preimageHex: string; amountPaidSat: number }> {
+		return { preimageHex: "00".repeat(32), amountPaidSat: input.amountSat };
+	}
+}
+
+// WalletInvoicePayer pays an L402 invoice through the embedded walletdk wallet.
+// walletdk hides the Ark↔Lightning swap: prepareSend quotes it (surfacing the
+// swap fee for the budget check), sendPrepared dispatches it, and the preimage
+// is read off the settled activity entry once the swap completes.
+export class WalletInvoicePayer implements InvoicePayer {
+	private readonly wallet: WalletService;
+
+	constructor(wallet: WalletService) {
+		this.wallet = wallet;
+	}
+
+	async payInvoice(input: PayInvoiceInput): Promise<{ preimageHex: string; amountPaidSat: number }> {
+		return this.wallet.payInvoice(input.invoice, input.amountSat);
+	}
+}

package/src/policy.ts

@@ -0,0 +1,209 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { BuyerPolicy } from "@lightninglabs/aperture-core";
+
+// DEFAULT_MAX_SAT_PER_REQUEST caps a single L402 payment when
+// PI402_MAX_SAT_PER_REQUEST is unset.
+const DEFAULT_MAX_SAT_PER_REQUEST = 1_000;
+
+// DEFAULT_DAILY_CAP_SAT caps cumulative daily spend when PI402_DAILY_CAP_SAT is
+// unset.
+const DEFAULT_DAILY_CAP_SAT = 100_000;
+
+// readSatCeiling parses a positive-integer sat ceiling from an environment
+// variable. A missing value yields the default. A present but non-numeric or
+// non-positive value throws, so a typo like "1,000" fails loudly instead of
+// silently disabling the cap (Number("1,000") is NaN, and every comparison with
+// NaN is false, which would wave all spending through).
+export function readSatCeiling(name: string, fallback: number): number {
+	const raw = process.env[name];
+	if (raw === undefined || raw === "") {
+		return fallback;
+	}
+	const value = Number(raw);
+	if (!Number.isFinite(value) || value <= 0) {
+		throw new Error(`${name} must be a positive number, got ${JSON.stringify(raw)}`);
+	}
+	return value;
+}
+
+// maxSatPerRequest returns the per-request spend ceiling from the environment.
+// The wallet payer reads the same ceiling to assert the quoted total outflow
+// before dispatching a send.
+export function maxSatPerRequest(): number {
+	return readSatCeiling("PI402_MAX_SAT_PER_REQUEST", DEFAULT_MAX_SAT_PER_REQUEST);
+}
+
+// PaymentScheme selects which HTTP authentication schemes the buyer will
+// answer a 402 with.
+export type PaymentScheme = "auto" | "l402";
+
+// paymentScheme reads the scheme preference from PI402_PAYMENT_SCHEME.
+//
+// The default is "auto": take a Payment (MPP) offer when the seller makes
+// one, and fall back to L402 otherwise. Aperture with --enablempp offers both
+// in a single merged WWW-Authenticate, so "auto" is what exercises MPP.
+// Setting "l402" pins the buyer to the older scheme, which is the escape
+// hatch if a seller's Payment offer turns out to be unsatisfiable.
+//
+// An unrecognized value throws rather than silently falling back. A typo in
+// the scheme name should not quietly change which protocol the money moves
+// over.
+export function paymentScheme(): PaymentScheme {
+	const raw = process.env.PI402_PAYMENT_SCHEME;
+	if (raw === undefined || raw === "") {
+		return "auto";
+	}
+
+	const value = raw.trim().toLowerCase();
+	if (value === "auto" || value === "l402") {
+		return value;
+	}
+
+	throw new Error(`PI402_PAYMENT_SCHEME must be "auto" or "l402", got ${JSON.stringify(raw)}`);
+}
+
+// mppIntents returns the Payment intents to accept, most wanted first.
+//
+// Under "l402" the list is empty, so no Payment offer matches and the buyer
+// takes the L402 door. Otherwise the default is "charge" alone: a session
+// holds a deposit the seller owes back, and reclaiming it needs a refund
+// invoice the wallet must mint and a close the process must remember to
+// send. Charge settles each request on its own and leaves nothing
+// outstanding, which is the right default for a wallet running unattended
+// inside an editor.
+//
+// PI402_MPP_INTENTS opts into more, as a comma-separated preference list
+// drawn from "session" and "charge".
+//
+// The session intent additionally requires a return-invoice minter. A
+// session's unspent deposit comes back through an amountless refund invoice
+// the buyer must supply at open, and the reference server refuses an open
+// without one, so a buyer with no minter would pay deposits whose opens are
+// guaranteed to be refused. The swap-backed embedded wallet cannot mint
+// amountless invoices (the daemon refuses a zero amount), so the extension
+// has no minter today and sessions stay off there; the dev harness can wire
+// one from a local lnd, which is what makes the regtest session flow
+// testable. A wavelength-side amountless receive is the upstream seam that
+// lifts this for the extension.
+export function mppIntents(options?: { hasReturnInvoiceMinter?: boolean }): readonly string[] {
+	if (paymentScheme() === "l402") {
+		return [];
+	}
+
+	const raw = process.env.PI402_MPP_INTENTS;
+	if (raw === undefined || raw === "") {
+		return ["charge"];
+	}
+
+	const intents = raw
+		.split(",")
+		.map((intent) => intent.trim().toLowerCase())
+		.filter((intent) => intent !== "");
+
+	for (const intent of intents) {
+		if (intent !== "charge" && intent !== "session") {
+			throw new Error(`PI402_MPP_INTENTS entries must be "charge" or "session", got ${JSON.stringify(intent)}`);
+		}
+	}
+	if (intents.length === 0) {
+		throw new Error("PI402_MPP_INTENTS must name at least one intent when set");
+	}
+
+	if (intents.includes("session") && !options?.hasReturnInvoiceMinter) {
+		throw new Error(
+			"PI402_MPP_INTENTS includes sessions, but no return-invoice minter is available: a session's " +
+				"refund needs an amountless invoice the embedded wallet cannot mint, and the server refuses " +
+				"an open without one, so the deposit would be paid for a guaranteed refusal",
+		);
+	}
+
+	return intents;
+}
+
+// utcDayKey returns a stable key for the current UTC calendar day, used to reset
+// the daily counter at the day boundary.
+function utcDayKey(now: Date): string {
+	return now.toISOString().slice(0, 10);
+}
+
+// SpentTodaySource supplies the sats already spent on the current UTC day,
+// typically summed from the durable receipt ledger.
+export interface SpentTodaySource {
+	spentTodaySat(): Promise<number>;
+}
+
+// buildBudgetPolicy constructs the buyer policy from environment ceilings. The
+// policy is asserted before any wallet action, on the quoted total outflow
+// (invoice principal plus swap fee), so a runaway session cannot drain the
+// wallet.
+//
+// With a spentToday source, the ledger is read fresh on every assertion and
+// combined with the in-memory counter, so neither a restart nor a concurrent
+// session can reset the day's spend to zero.
+export function buildBudgetPolicy(_pi: ExtensionAPI, spentTodaySource?: SpentTodaySource): BuyerPolicy {
+	const perRequestCap = maxSatPerRequest();
+	const dailyCapSat = readSatCeiling("PI402_DAILY_CAP_SAT", DEFAULT_DAILY_CAP_SAT);
+
+	// spentToday tracks cumulative spend for the daily ceiling, reset at the UTC
+	// day boundary.
+	let spentToday = 0;
+	let currentDay = utcDayKey(new Date());
+
+	return {
+		async assertAllowed(ctx: { amountSat: number; host: string; url: string; routeId?: string }): Promise<void> {
+			// Read the ledger fresh on every assertion: it is the shared
+			// ground truth across restarts and concurrent sessions. Payments
+			// are rare and the file is small, so the read is cheap. An
+			// unreadable ledger degrades to the in-memory counter alone; the
+			// degradation is logged because a spend cap silently losing its
+			// memory should never be invisible.
+			let ledgerToday = 0;
+			if (spentTodaySource) {
+				try {
+					ledgerToday = await spentTodaySource.spentTodaySat();
+				} catch (err) {
+					console.warn("pi-402: receipt ledger unreadable, daily cap using in-memory spend only:", err);
+				}
+			}
+
+			// Everything below is synchronous, so concurrent assertions in
+			// this process cannot interleave between the check and the
+			// counter update.
+			const day = utcDayKey(new Date());
+			if (day !== currentDay) {
+				currentDay = day;
+				spentToday = 0;
+			}
+
+			if (ctx.amountSat > perRequestCap) {
+				throw new Error(`payment ${ctx.amountSat} sat exceeds per-request cap ${perRequestCap} sat`);
+			}
+
+			// The in-memory counter carries in-flight amounts the ledger
+			// cannot see yet (and quotes for payments that later failed);
+			// the ledger carries settled spends from other sessions this
+			// counter never saw. Take the max: it is conservative under
+			// either gap. Units differ slightly, quoted face value in the
+			// counter vs fee-inclusive paidSat in the ledger, which also
+			// errs on the conservative side.
+			//
+			// The residual overshoot bound across sessions is the sum of
+			// all in-flight (asserted, not yet settled) amounts in OTHER
+			// processes, each bounded by their per-request cap; unsettled
+			// spends are invisible to this process until they reach the
+			// ledger.
+			const effectiveSpent = Math.max(spentToday, ledgerToday);
+			if (effectiveSpent + ctx.amountSat > dailyCapSat) {
+				throw new Error(`payment would exceed daily cap ${dailyCapSat} sat`);
+			}
+
+			// NOTE: the counter is incremented here, before the wallet actually
+			// pays. The paying fetch calls assertAllowed ahead of settlement and
+			// exposes no post-payment callback, so a failed payment is not rolled
+			// back off the daily counter. This errs conservative (a failed
+			// payment still consumes budget), which is the safe direction for a
+			// spend cap; a clean rollback needs a hook the library does not offer.
+			spentToday = effectiveSpent + ctx.amountSat;
+		},
+	};
+}