@freebuild/pi 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,64 @@
+Freebuild Proprietary License
+Copyright (c) 2026 Freebuild. All rights reserved.
+
+This license applies to the Freebuild repository and the Freebuild service,
+except for third-party components, which remain under their own licenses.
+
+This software, including its source code, documentation, and associated files
+(the "Software"), is proprietary and is not open source.
+
+1. Limited license
+
+Subject to your compliance with the Freebuild Terms of Service
+(https://freebuild.dev/terms.html), Freebuild grants you a limited,
+non-exclusive, non-transferable, non-sublicensable, revocable license to
+install and use the Software on devices you control, solely for your internal
+personal or business purposes in connection with the Freebuild service.
+
+2. Restrictions
+
+You may not:
+
+(a) copy, redistribute, sublicense, sell, rent, lease, or otherwise make the
+Software available to any third party;
+(b) modify, translate, or create derivative works of the Software;
+(c) reverse engineer, decompile, or disassemble the Software, except to the
+extent permitted by applicable law;
+(d) remove or alter any copyright, trademark, or other proprietary notices;
+(e) use the Software to build, operate, or provide a competing coding-agent
+product or service; or
+(f) use the Software after your Freebuild service access has been terminated.
+
+3. Ownership
+
+Freebuild and its licensors retain all right, title, and interest in the
+Software, including all intellectual property rights. No rights are granted
+except as expressly stated in this license.
+
+4. Trademarks
+
+This license does not grant any right to use the Freebuild name, logo, or other
+trademarks.
+
+5. No warranty
+
+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.
+
+6. Limitation of liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, FREEBUILD WILL NOT BE LIABLE FOR ANY
+INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR FOR ANY
+LOSS OF PROFITS, DATA, OR BUSINESS, ARISING OUT OF OR IN CONNECTION WITH THE
+SOFTWARE.
+
+7. Termination
+
+This license terminates automatically if you breach its terms. On termination,
+you must stop using the Software and delete all copies.
+
+8. Contact
+
+For licensing questions, contact Freebuild through
+https://freebuild.dev/contact.html.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# Freebuild for Pi
 
-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 extension that connects Pi to the Freebuild broker and shows the sponsor panel during sponsored runs.
+
+This is the Pi beta.
+
+## Install
+
+```bash
+pi install npm:@freebuild/pi@latest
+```
+
+For local development from this repository:
+
+```bash
+pi install "$(pwd)/pi-extension"
+```
+
+Restart Pi, then:
+
+```text
+/freebuild-license
+```
+
+Paste a Freebuild license key, or pass it directly:
+
+```text
+/freebuild-license fb_...
+```
+
+The command verifies the key against the broker, saves it to `~/.config/freebuild/credentials.json`, and selects the Freebuild model.
+
+## Use
+
+```text
+/model
+```
+
+Choose:
+
+```text
+freebuild/deepseek-flash
+```
+
+The extension registers the provider as `freebuild` and sends:
+
+- `Authorization: Bearer <license key>`
+- `X-Freebuild-Install: <install id>`
+- `X-Freebuild-Client: pi/0.0.2`
+- `X-Freebuild-Client: pi/0.0.2-headless` in print and JSON modes
+
+## Sponsor panel
+
+The panel appears above the editor while a sponsored run is active. On terminals at least 80 columns wide it uses a large full-width layout with a big image and copy block. Narrow terminals fall back to the compact panel.
+
+- `SPONSORED` for paid campaigns
+- `AFFILIATE` for affiliate campaigns
+- `FREEBUILD` for house inventory
+- `ADVERTISE` for house advertising inventory
+
+Print and JSON modes do not render the panel and do not record impressions. That avoids counting an ad the user could not see.
+
+Open the sponsor with `alt+o` or:
+
+```text
+/freebuild-sponsor
+```
+
+The plugin records `open` and `close` events for each run and uses the tracked click endpoint when possible. Image-only campaigns always render their campaign label, the brand, and the open hint, so Pi never shows a terminal panel with only an image.
+
+## Commands
+
+```text
+/freebuild-license [key]  Save and verify a license
+/freebuild-sponsor        Open the current sponsor
+/freebuild-status         Show license, model, install, and broker
+```
+
+## Environment
+
+```text
+FREEBUILD_CREDENTIALS   Override the credentials file path
+FREEBUILD_API_URL       Override the web origin
+FREEBUILD_BROKER_URL    Override the broker URL
+FREEBUILD_SPONSOR_URL   Override the sponsor panel URL
+FREEBUILD_LICENSE_KEY   Override the stored license key
+```
+
+## Development
+
+Load the extension without installing it:
+
+```bash
+pi --no-extensions -e ./pi-extension --list-models freebuild
+```
+
+The package has no build step. Pi loads TypeScript through jiti.
+
+## License
+
+Proprietary. Copyright (c) 2026 Freebuild. All rights reserved.
+
+This package is licensed under the Freebuild Proprietary License. See
+[LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@freebuild/pi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "author": "Freebuild <hello@freebuild.dev> (https://freebuild.dev)",
+  "description": "Freebuild sponsored model provider and sponsor panel for Pi",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "keywords": [
+    "pi-package",
+    "freebuild",
+    "sponsor",
+    "coding-agent"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,1081 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	getCapabilities,
+	HStack,
+	Image,
+	truncateToWidth,
+	visibleWidth,
+	wrapTextWithAnsi,
+	type Component,
+	type TUI,
+} from "@earendil-works/pi-tui";
+
+const PLUGIN_VERSION = "0.0.2";
+const CLIENT_ID = `pi/${PLUGIN_VERSION}`;
+const WIDGET_KEY = "freebuild-sponsor";
+const DEFAULT_API_URL = "https://freebuild.dev";
+const DEFAULT_BROKER_URL = "https://freebuild.dev/broker";
+const MAX_IMAGE_BYTES = 3_000_000;
+const REQUEST_TIMEOUT_MS = 6_000;
+
+type Theme = ExtensionContext["ui"]["theme"];
+
+interface Credentials {
+	licenseKey?: string;
+	installId?: string;
+	brokerUrl?: string;
+	apiUrl?: string;
+}
+
+interface PanelCampaign {
+	id: string;
+	brand: string;
+	label: string;
+	kicker: string;
+	title: string;
+	body: string;
+	url: string;
+	clickUrl: string;
+	eventUrl: string;
+	accent: string;
+	imageUrl: string;
+	imageOnly: boolean;
+	wordmark: string;
+	showWordmark: boolean;
+	align: "left" | "center";
+}
+
+interface ImageData {
+	base64: string;
+	mimeType: string;
+}
+
+const credentialsPath =
+	process.env.FREEBUILD_CREDENTIALS ||
+	join(homedir(), ".config", "freebuild", "credentials.json");
+
+const credentials = readCredentials();
+const apiUrl = (
+	process.env.FREEBUILD_API_URL ||
+	credentials.apiUrl ||
+	DEFAULT_API_URL
+).replace(/\/+$/, "");
+const brokerUrl = (
+	process.env.FREEBUILD_BROKER_URL ||
+	credentials.brokerUrl ||
+	DEFAULT_BROKER_URL
+).replace(/\/+$/, "");
+const sponsorUrl = (
+	process.env.FREEBUILD_SPONSOR_URL || `${apiUrl}/api/sponsor/panel`
+).replace(/\/+$/, "");
+
+let installId = String(credentials.installId || "").trim();
+if (!installId) {
+	installId = createId("install-");
+	saveCredentials({ installId });
+}
+
+let licenseKey = (
+	process.env.FREEBUILD_LICENSE_KEY ||
+	credentials.licenseKey ||
+	""
+).trim();
+let sessionId = createId("session-");
+let runId = "";
+let runActive = false;
+let runToken = 0;
+let openSent = false;
+let panelStartedAt = 0;
+let shownCampaign: PanelCampaign | undefined;
+
+function readCredentials(): Credentials {
+	try {
+		const raw = readFileSync(credentialsPath, "utf8").replace(/^\uFEFF/, "");
+		const value = JSON.parse(raw) as unknown;
+		return value && typeof value === "object" ? (value as Credentials) : {};
+	} catch {
+		return {};
+	}
+}
+
+function saveCredentials(patch: Partial<Credentials>) {
+	const next = { ...readCredentials(), ...patch };
+	try {
+		mkdirSync(dirname(credentialsPath), { recursive: true });
+		writeFileSync(credentialsPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+		try {
+			chmodSync(credentialsPath, 0o600);
+		} catch {
+			// Windows and some filesystems do not implement chmod.
+		}
+	} catch {
+		// A read-only home directory must not break the current process.
+	}
+}
+
+function createId(prefix: string): string {
+	return `${prefix}${randomUUID().replace(/-/g, "").slice(0, 28)}`;
+}
+
+function normalizeSessionId(value: string): string {
+	const cleaned = value.replace(/[^a-zA-Z0-9._-]/g, "").slice(0, 80);
+	return cleaned.length >= 6 ? cleaned : createId("session-");
+}
+
+function stringValue(value: unknown): string {
+	return typeof value === "string" ? value.trim() : "";
+}
+
+function normalizeLabel(value: unknown): string {
+	const label = stringValue(value).toUpperCase();
+	return ["SPONSORED", "AFFILIATE", "FREEBUILD", "ADVERTISE"].includes(label)
+		? label
+		: "SPONSORED";
+}
+
+function normalizeCampaign(value: unknown): PanelCampaign | undefined {
+	if (!value || typeof value !== "object") {
+		return undefined;
+	}
+
+	const raw = value as Record<string, unknown>;
+	const id = stringValue(raw.id);
+	if (!id) {
+		return undefined;
+	}
+
+	const accent = stringValue(raw.accent).toLowerCase();
+	const align = stringValue(raw.align).toLowerCase();
+
+	return {
+		id,
+		brand: stringValue(raw.brand),
+		label: normalizeLabel(raw.label || raw.sponsor),
+		kicker: stringValue(raw.kicker),
+		title: stringValue(raw.title),
+		body: stringValue(raw.body),
+		url: stringValue(raw.url),
+		clickUrl: stringValue(raw.clickUrl) || stringValue(raw.url),
+		eventUrl: stringValue(raw.eventUrl),
+		accent: /^#[0-9a-f]{6}$/i.test(accent) ? accent : "#5b8cff",
+		imageUrl: stringValue(raw.imageUrl),
+		imageOnly: Boolean(raw.imageOnly),
+		wordmark: stringValue(raw.wordmark).toUpperCase(),
+		showWordmark: raw.showWordmark !== false,
+		align: align === "left" ? "left" : "center",
+	};
+}
+
+function houseFallback(): PanelCampaign {
+	return {
+		id: "house",
+		brand: "Freebuild",
+		label: "FREEBUILD",
+		kicker: "",
+		title: "Build more for less.",
+		body: "The sponsor panel is temporarily unavailable. Check plans or ask about sponsoring Freebuild.",
+		url: `${apiUrl}/terminal/pricing.html`,
+		clickUrl: `${apiUrl}/terminal/pricing.html`,
+		eventUrl: "",
+		accent: "#5b8cff",
+		imageUrl: "",
+		imageOnly: false,
+		wordmark: "FREEBUILD",
+		showWordmark: true,
+		align: "center",
+	};
+}
+
+function loadingPanel(): PanelCampaign {
+	return {
+		...houseFallback(),
+		title: "Sponsored session",
+		body: "Loading the current sponsor...",
+	};
+}
+
+async function request(
+	url: string,
+	init: RequestInit = {},
+	timeoutMs = REQUEST_TIMEOUT_MS,
+): Promise<Response> {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		return await fetch(url, { ...init, signal: controller.signal });
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+async function fetchJson(
+	url: string,
+	init: RequestInit = {},
+	timeoutMs = REQUEST_TIMEOUT_MS,
+): Promise<any> {
+	const response = await request(url, init, timeoutMs);
+	if (!response.ok) {
+		throw new Error(`HTTP ${response.status}`);
+	}
+	return response.json();
+}
+
+function authorizationHeaders(): Record<string, string> {
+	const headers: Record<string, string> = {
+		accept: "application/json",
+		"x-freebuild-install": installId,
+		"x-freebuild-client": CLIENT_ID,
+	};
+	if (licenseKey) {
+		headers.authorization = `Bearer ${licenseKey}`;
+	}
+	return headers;
+}
+
+async function fetchPanel(
+	run: string,
+	preview = false,
+): Promise<PanelCampaign | undefined> {
+	const params = new URLSearchParams();
+	if (preview) {
+		params.set("preview", "1");
+	} else if (run) {
+		params.set("runId", run);
+	}
+	params.set("client", CLIENT_ID);
+
+	const separator = sponsorUrl.includes("?") ? "&" : "?";
+	const data = await fetchJson(
+		`${sponsorUrl}${separator}${params.toString()}`,
+		{ headers: authorizationHeaders() },
+	);
+	return normalizeCampaign(data?.campaign ?? data);
+}
+
+async function loadImage(campaign: PanelCampaign): Promise<ImageData | undefined> {
+	if (!campaign.imageUrl || !getCapabilities().images) {
+		return undefined;
+	}
+	if (!/^https?:\/\//i.test(campaign.imageUrl)) {
+		return undefined;
+	}
+
+	try {
+		const response = await request(
+			campaign.imageUrl,
+			{ headers: { accept: "image/*" } },
+			REQUEST_TIMEOUT_MS,
+		);
+		if (!response.ok) {
+			return undefined;
+		}
+		const mimeType =
+			(response.headers.get("content-type") || "").split(";")[0].trim().toLowerCase();
+		if (!mimeType.startsWith("image/")) {
+			return undefined;
+		}
+		const buffer = Buffer.from(await response.arrayBuffer());
+		if (buffer.length === 0 || buffer.length > MAX_IMAGE_BYTES) {
+			return undefined;
+		}
+		return { base64: buffer.toString("base64"), mimeType };
+	} catch {
+		return undefined;
+	}
+}
+
+function sendEvent(
+	campaign: PanelCampaign,
+	event: "open" | "close",
+	durationMs: number,
+	eventRunId: string,
+) {
+	if (!licenseKey || !campaign.eventUrl || !eventRunId || campaign.id === "house") {
+		return;
+	}
+
+	void request(
+		campaign.eventUrl,
+		{
+			method: "POST",
+			keepalive: true,
+			headers: {
+				...authorizationHeaders(),
+				"content-type": "application/json",
+			},
+			body: JSON.stringify({
+				campaignId: campaign.id,
+				sessionId,
+				runId: eventRunId,
+				client: CLIENT_ID,
+				event,
+				durationMs,
+				tokens: 0,
+			}),
+		},
+		REQUEST_TIMEOUT_MS,
+	).catch(() => {
+		// Exposure tracking is best-effort and must never interrupt the agent.
+	});
+}
+
+function panelLabel(campaign: PanelCampaign): string {
+	return campaign.label || (campaign.id === "house" ? "FREEBUILD" : "SPONSORED");
+}
+
+function panelBrand(campaign: PanelCampaign): string {
+	return (
+		campaign.brand ||
+		(campaign.showWordmark ? campaign.wordmark : "") ||
+		(campaign.id === "house" ? "Freebuild" : "Sponsor")
+	);
+}
+
+function panelHeading(campaign: PanelCampaign): string {
+	const label = panelLabel(campaign);
+	const brand = panelBrand(campaign);
+	return brand && brand.toUpperCase() !== label ? `${label}  ${brand}` : label;
+}
+
+function styledHeading(theme: Theme, campaign: PanelCampaign): string {
+	const label = panelLabel(campaign);
+	const brand = panelBrand(campaign);
+	return brand && brand.toUpperCase() !== label
+		? `${theme.fg("accent", theme.bold(label))}  ${theme.bold(brand)}`
+		: theme.fg("accent", theme.bold(label));
+}
+
+function panelTextLines(campaign: PanelCampaign, width: number): string[] {
+	const inner = Math.max(20, Math.min(width, 96));
+	const lines = [panelHeading(campaign)];
+
+	if (campaign.kicker) {
+		lines.push(...wrapTextWithAnsi(campaign.kicker, inner).slice(0, 1));
+	}
+	if (campaign.title) {
+		lines.push(...wrapTextWithAnsi(campaign.title, inner).slice(0, 2));
+	}
+	if (campaign.body) {
+		lines.push("");
+		lines.push(...wrapTextWithAnsi(campaign.body, inner).slice(0, 3));
+	}
+	lines.push("");
+	lines.push("alt+o or /freebuild-sponsor to open");
+
+	return lines.map((line) => truncateToWidth(line, inner));
+}
+
+class SponsorCopy implements Component {
+	private readonly theme: Theme;
+	private readonly campaign: PanelCampaign;
+
+	constructor(theme: Theme, campaign: PanelCampaign) {
+		this.theme = theme;
+		this.campaign = campaign;
+	}
+
+	invalidate() {}
+
+	render(width: number): string[] {
+		const theme = this.theme;
+		const lines = [styledHeading(theme, this.campaign)];
+
+		if (this.campaign.kicker) {
+			lines.push(
+				...wrapTextWithAnsi(
+					theme.fg("muted", this.campaign.kicker),
+					width,
+				).slice(0, 1),
+			);
+		}
+		if (this.campaign.title) {
+			lines.push(
+				...wrapTextWithAnsi(theme.bold(this.campaign.title), width).slice(
+					0,
+					3,
+				),
+			);
+		}
+		if (this.campaign.body) {
+			lines.push("");
+			lines.push(
+				...wrapTextWithAnsi(
+					theme.fg("muted", this.campaign.body),
+					width,
+				).slice(0, 4),
+			);
+		}
+
+		lines.push("");
+		lines.push(theme.fg("dim", "alt+o or /freebuild-sponsor to open"));
+
+		return lines.map((line) => truncateToWidth(line, width));
+	}
+}
+
+type StackItem = {
+	component: Component;
+	basis?: number;
+	grow?: number;
+	shrink?: number;
+	minSize?: number;
+	maxSize?: number;
+};
+
+export class SponsorPanel implements Component {
+	private readonly theme: Theme;
+	private readonly campaign: PanelCampaign;
+	private readonly image?: Image;
+	private readonly tui?: TUI;
+	private readonly copy: SponsorCopy;
+
+	constructor(
+		theme: Theme,
+		campaign: PanelCampaign,
+		image?: Image,
+		tui?: TUI,
+	) {
+		this.theme = theme;
+		this.campaign = campaign;
+		this.image = image;
+		this.tui = tui;
+		this.copy = new SponsorCopy(theme, campaign);
+	}
+
+	invalidate() {
+		this.image?.invalidate();
+		this.copy.invalidate();
+	}
+
+	render(width: number): string[] {
+		const rows = this.tui?.terminal.rows ?? 24;
+		if (width >= 80 && rows >= 30) {
+			return this.renderLarge(width, rows);
+		}
+		return this.renderCompact(width);
+	}
+
+	private renderLarge(width: number, rows: number): string[] {
+		const theme = this.theme;
+		const inner = Math.max(40, width - 2);
+		const targetHeight = Math.max(14, Math.min(28, Math.floor(rows * 0.5)));
+		const bodyHeight = Math.max(10, targetHeight - 2);
+		const hasImage = Boolean(this.image);
+		const imageWidth = hasImage
+			? Math.max(24, Math.min(56, Math.floor(inner * 0.38)))
+			: 0;
+		const copyWidth = hasImage
+			? Math.max(24, inner - imageWidth - 2)
+			: inner;
+		const children: StackItem[] = [];
+
+		if (this.image) {
+			children.push({
+				component: this.image,
+				basis: imageWidth,
+				minSize: imageWidth,
+				maxSize: imageWidth,
+				shrink: 0,
+			});
+		}
+		children.push({
+			component: this.copy,
+			basis: copyWidth,
+			grow: 1,
+			minSize: 20,
+		});
+
+		const stack = new HStack(children, {
+			gap: hasImage ? 2 : 0,
+			align: "center",
+		});
+		let body = stack.render(inner);
+		if (body.length > bodyHeight) {
+			body = body.slice(0, bodyHeight);
+		}
+
+		const padTop = Math.max(0, Math.floor((bodyHeight - body.length) / 2));
+		const padBottom = Math.max(0, bodyHeight - body.length - padTop);
+		const divider = theme.fg("borderMuted", "\u2500".repeat(inner));
+
+		return [
+			divider,
+			...Array<string>(padTop).fill(""),
+			...body,
+			...Array<string>(padBottom).fill(""),
+			divider,
+		].map((line) => truncateToWidth(line, inner));
+	}
+
+	private renderCompact(width: number): string[] {
+		const theme = this.theme;
+		const inner = Math.max(20, Math.min(width - 2, 96));
+		const lines: string[] = [];
+		const border = (text: string) => theme.fg("borderMuted", text);
+
+		lines.push(border(`\u250c${"\u2500".repeat(inner)}\u2510`));
+		lines.push(this.row(styledHeading(theme, this.campaign), inner));
+
+		if (this.campaign.kicker) {
+			lines.push(
+				...this.wrapped(
+					theme.fg("muted", this.campaign.kicker),
+					inner,
+					1,
+				),
+			);
+		}
+		if (this.campaign.title) {
+			lines.push(
+				...this.wrapped(theme.bold(this.campaign.title), inner, 2),
+			);
+		}
+		if (this.campaign.body) {
+			lines.push(
+				...this.wrapped(theme.fg("muted", this.campaign.body), inner, 2),
+			);
+		}
+
+		if (this.image) {
+			try {
+				const imageWidth = Math.min(width, 14);
+				lines.push(...this.image.render(imageWidth).slice(0, 6));
+			} catch {
+				// A terminal-level image failure leaves the text panel intact.
+			}
+		}
+
+		lines.push(
+			this.row(
+				theme.fg("dim", "alt+o or /freebuild-sponsor to open"),
+				inner,
+			),
+		);
+		lines.push(border(`\u2514${"\u2500".repeat(inner)}\u2518`));
+
+		return lines;
+	}
+
+	private wrapped(text: string, width: number, limit: number): string[] {
+		return wrapTextWithAnsi(text, width)
+			.slice(0, limit)
+			.map((line) => this.row(line, width));
+	}
+
+	private row(text: string, width: number): string {
+		const clipped = truncateToWidth(text, width);
+		const padding = Math.max(0, width - visibleWidth(clipped));
+		return `${this.theme.fg("borderMuted", "\u2502")}${clipped}${" ".repeat(padding)}${this.theme.fg("borderMuted", "\u2502")}`;
+	}
+}
+
+function showPanel(
+	ctx: ExtensionContext,
+	campaign: PanelCampaign,
+	image?: ImageData,
+): boolean {
+	try {
+		if (ctx.mode === "rpc") {
+			// RPC clients receive string widget lines. Component factories and
+			// terminal images are ignored in this mode.
+			ctx.ui.setWidget(WIDGET_KEY, panelTextLines(campaign, 96), {
+				placement: "aboveEditor",
+			});
+			return true;
+		}
+
+		ctx.ui.setWidget(
+			WIDGET_KEY,
+			(tui, theme) => {
+				let renderedImage: Image | undefined;
+				if (image && getCapabilities().images) {
+					const maxImageWidth = Math.max(
+						24,
+						Math.min(56, Math.floor(tui.terminal.columns * 0.35)),
+					);
+					const maxImageHeight = Math.max(
+						8,
+						Math.min(22, Math.floor(tui.terminal.rows * 0.45)),
+					);
+					renderedImage = new Image(
+						image.base64,
+						image.mimeType,
+						{ fallbackColor: (value) => theme.fg("dim", value) },
+						{
+							maxWidthCells: maxImageWidth,
+							maxHeightCells: maxImageHeight,
+							filename: "sponsor",
+						},
+					);
+				}
+				return new SponsorPanel(theme, campaign, renderedImage, tui);
+			},
+			{ placement: "aboveEditor" },
+		);
+		return true;
+	} catch {
+		// The panel must not take down a session during a terminal transition.
+		return false;
+	}
+}
+
+function clearPanel(ctx: ExtensionContext) {
+	try {
+		ctx.ui.setWidget(WIDGET_KEY, undefined);
+	} catch {
+		// The widget may already be gone during shutdown.
+	}
+}
+
+function isFreebuildModel(ctx: ExtensionContext): boolean {
+	return String(ctx.model?.provider || "") === "freebuild";
+}
+
+function syncStatus(ctx: ExtensionContext) {
+	try {
+		if (isFreebuildModel(ctx)) {
+			ctx.ui.setStatus(
+				"freebuild",
+				licenseKey ? "Freebuild sponsored" : "Freebuild: no license",
+			);
+		} else {
+			ctx.ui.setStatus("freebuild", undefined);
+		}
+	} catch {
+		// Status display is cosmetic.
+	}
+}
+
+async function showRunPanel(ctx: ExtensionContext, token: number) {
+	const currentRun = runId;
+	let campaign = await fetchPanel(currentRun).catch(() => undefined);
+	if (!campaign) {
+		campaign = houseFallback();
+	}
+	if (!runActive || token !== runToken) {
+		return;
+	}
+
+	// Image-only campaigns still render the campaign label, the brand, and the
+	// open hint. Pi never shows a terminal panel with only an image.
+
+	if (!showPanel(ctx, campaign)) {
+		return;
+	}
+
+	shownCampaign = campaign;
+	panelStartedAt = Date.now();
+
+	if (campaign.id !== "house" && campaign.eventUrl) {
+		openSent = true;
+		sendEvent(campaign, "open", 0, currentRun);
+	}
+
+	void loadImage(campaign).then((image) => {
+		if (
+			!image ||
+			!runActive ||
+			token !== runToken ||
+			shownCampaign?.id !== campaign.id
+		) {
+			return;
+		}
+		showPanel(ctx, campaign, image);
+	});
+}
+
+function beginRun(ctx: ExtensionContext) {
+	if (runActive) {
+		return;
+	}
+	syncStatus(ctx);
+	if (!isFreebuildModel(ctx)) {
+		clearPanel(ctx);
+		return;
+	}
+
+	// Print and JSON modes cannot render a panel. Do not record an impression
+	// when the user never had a chance to see one.
+	if (!ctx.hasUI) {
+		return;
+	}
+
+	if (!licenseKey) {
+		ctx.ui.notify(
+			"Freebuild license missing. Run /freebuild-license.",
+			"warning",
+		);
+		return;
+	}
+
+	runActive = true;
+	const token = ++runToken;
+	runId = createId("run-");
+	openSent = false;
+	panelStartedAt = 0;
+	shownCampaign = undefined;
+
+	// Show the mandatory panel immediately, then replace it when the selected
+	// campaign arrives. The loading panel is house inventory and is not tracked.
+	showPanel(ctx, loadingPanel());
+	void showRunPanel(ctx, token);
+}
+
+function endRun(ctx: ExtensionContext) {
+	if (!runActive) {
+		clearPanel(ctx);
+		return;
+	}
+
+	const campaign = shownCampaign;
+	const closingRunId = runId;
+	const durationMs = panelStartedAt ? Date.now() - panelStartedAt : 0;
+	const shouldClose =
+		openSent &&
+		Boolean(campaign) &&
+		campaign!.id !== "house" &&
+		Boolean(campaign!.eventUrl) &&
+		Boolean(closingRunId);
+
+	runActive = false;
+	runToken++;
+	runId = "";
+	openSent = false;
+	panelStartedAt = 0;
+	shownCampaign = undefined;
+	clearPanel(ctx);
+
+	if (shouldClose) {
+		sendEvent(campaign!, "close", durationMs, closingRunId);
+	}
+}
+
+function registerProvider(pi: ExtensionAPI, key: string) {
+	if (!key) {
+		return;
+	}
+
+	pi.registerProvider("freebuild", {
+		name: "Freebuild",
+		baseUrl: `${brokerUrl}/v1`,
+		apiKey: key,
+		api: "openai-completions",
+		authHeader: true,
+		headers: {
+			"X-Freebuild-Install": installId,
+			"X-Freebuild-Client": CLIENT_ID,
+		},
+		models: [
+			{
+				id: "deepseek-flash",
+				name: "DeepSeek V4.1 Flash 1017",
+				reasoning: true,
+				thinkingLevelMap: {
+					minimal: null,
+					low: "low",
+					medium: null,
+					high: "high",
+					max: "max",
+				},
+				input: ["text", "image"],
+				inputLimits: {
+					images: {
+						resize: {
+							maxWidth: 2000,
+							maxHeight: 2000,
+							maxBytes: 4718592,
+							jpegQuality: 80,
+						},
+					},
+				},
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+				contextWindow: 1_000_000,
+				maxTokens: 384_000,
+				compat: {
+					supportsStore: false,
+					supportsDeveloperRole: false,
+					supportsReasoningEffort: true,
+					supportsUsageInStreaming: true,
+					supportsFinishReason: true,
+					maxTokensField: "max_tokens",
+					requiresReasoningContentOnAssistantMessages: true,
+					thinkingFormat: "deepseek",
+					supportsStrictMode: true,
+				},
+			},
+		],
+	});
+}
+
+async function probeLicense(
+	key: string,
+): Promise<{ ok: true } | { ok: false; message: string }> {
+	try {
+		const response = await request(
+			`${brokerUrl}/api/me/entitlement`,
+			{
+				headers: {
+					accept: "application/json",
+					authorization: `Bearer ${key}`,
+					"x-freebuild-install": installId,
+					"x-freebuild-client": CLIENT_ID,
+				},
+			},
+			REQUEST_TIMEOUT_MS,
+		);
+
+		if (response.status === 401 || response.status === 404) {
+			return {
+				ok: false,
+				message:
+					"That license key is not active. It may have been rotated, revoked, or cancelled.",
+			};
+		}
+		if (response.status === 403) {
+			return {
+				ok: false,
+				message:
+					"That license is not on the sponsored plan, or it is bound to another install.",
+			};
+		}
+		if (!response.ok) {
+			return {
+				ok: false,
+				message: `The Freebuild broker returned ${response.status}. Try again in a moment.`,
+			};
+		}
+
+		const data = (await response.json()) as any;
+		if (!data?.sponsored || data?.panel === false) {
+			return {
+				ok: false,
+				message:
+					"That license is not on the sponsored plan. The broker rejected it.",
+			};
+		}
+		return { ok: true };
+	} catch {
+		return {
+			ok: false,
+			message:
+				"Could not reach the Freebuild broker. Check your connection and try again.",
+		};
+	}
+}
+
+function openUrl(url: string): boolean {
+	if (!/^https?:\/\//i.test(url)) {
+		return false;
+	}
+
+	const commands: Array<[string, string[]]> =
+		process.platform === "win32"
+			? [
+					["rundll32.exe", ["url.dll,FileProtocolHandler", url]],
+					["explorer.exe", [url]],
+					["cmd.exe", ["/d", "/s", "/c", "start", "", url]],
+				]
+			: process.platform === "darwin"
+				? [["open", [url]]]
+				: [
+						["xdg-open", [url]],
+						["gio", ["open", url]],
+					];
+
+	const attempt = (index: number): boolean => {
+		const command = commands[index];
+		if (!command) {
+			return false;
+		}
+		try {
+			const child = spawn(command[0], command[1], {
+				detached: true,
+				stdio: "ignore",
+			});
+			child.once("error", () => {
+				if (index + 1 < commands.length) {
+					attempt(index + 1);
+				}
+			});
+			child.unref();
+			return true;
+		} catch {
+			return index + 1 < commands.length ? attempt(index + 1) : false;
+		}
+	};
+
+	return attempt(0);
+}
+
+async function openSponsor(ctx: ExtensionContext) {
+	if (!licenseKey) {
+		ctx.ui.notify("Run /freebuild-license first.", "warning");
+		return;
+	}
+
+	let campaign = shownCampaign;
+	if (!campaign) {
+		campaign = await fetchPanel("", true).catch(() => undefined);
+	}
+	campaign ||= houseFallback();
+
+	const target = campaign.url || campaign.clickUrl;
+	if (!target) {
+		ctx.ui.notify("No sponsor link is available.", "warning");
+		return;
+	}
+
+	const activeRun = runId;
+	if (!activeRun || campaign.id === "house" || !campaign.clickUrl) {
+		if (!openUrl(target)) {
+			ctx.ui.notify(`Sponsor: ${target}`, "info");
+		}
+		return;
+	}
+
+	try {
+		const url = new URL(campaign.clickUrl);
+		url.searchParams.set("sid", sessionId);
+		url.searchParams.set("iid", installId);
+		url.searchParams.set("rid", activeRun);
+		url.searchParams.set("format", "json");
+
+		const data = await fetchJson(url.toString(), {
+			headers: authorizationHeaders(),
+			keepalive: true,
+		});
+		const destination = String(data?.url || "");
+		if (!destination || !openUrl(destination)) {
+			throw new Error("missing click destination");
+		}
+	} catch {
+		if (!openUrl(target)) {
+			ctx.ui.notify(`Sponsor: ${target}`, "info");
+		}
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	if (licenseKey) {
+		registerProvider(pi, licenseKey);
+	}
+
+	pi.on("before_provider_headers", (event, ctx) => {
+		const installKey = Object.keys(event.headers).find(
+			(key) => key.toLowerCase() === "x-freebuild-install",
+		);
+		if (!installKey) {
+			return;
+		}
+
+		// Mark headless runs separately. The abuse report can then ignore
+		// usage that never had a panel to show.
+		const clientKey = Object.keys(event.headers).find(
+			(key) => key.toLowerCase() === "x-freebuild-client",
+		);
+		if (clientKey) {
+			event.headers[clientKey] = null;
+		}
+		event.headers["x-freebuild-client"] =
+			ctx.mode === "tui" || ctx.mode === "rpc"
+				? CLIENT_ID
+				: `${CLIENT_ID}-headless`;
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		sessionId = normalizeSessionId(ctx.sessionManager.getSessionId());
+		syncStatus(ctx);
+	});
+
+	pi.on("agent_start", (_event, ctx) => {
+		beginRun(ctx);
+	});
+
+	pi.on("agent_settled", (_event, ctx) => {
+		endRun(ctx);
+	});
+
+	pi.on("model_select", (_event, ctx) => {
+		syncStatus(ctx);
+		if (!isFreebuildModel(ctx)) {
+			endRun(ctx);
+		}
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		endRun(ctx);
+	});
+
+	pi.registerCommand("freebuild-license", {
+		description: "Save and verify a Freebuild license key",
+		handler: async (args, ctx) => {
+			const entered =
+				args.trim() ||
+				(await ctx.ui.input(
+					"Freebuild license key",
+					"fb_...",
+				)) ||
+				"";
+			const key = entered.trim();
+			if (!key) {
+				return;
+			}
+
+			const probe = await probeLicense(key);
+			if (!probe.ok) {
+				ctx.ui.notify(probe.message, "error");
+				return;
+			}
+
+			licenseKey = key;
+			saveCredentials({ licenseKey: key, installId, brokerUrl, apiUrl });
+			registerProvider(pi, key);
+
+			const model = ctx.modelRegistry.find("freebuild", "deepseek-flash");
+			const selected = model ? await pi.setModel(model) : false;
+			ctx.ui.notify(
+				selected
+					? "Freebuild activated. Model set to DeepSeek V4.1 Flash 1017."
+					: "Freebuild activated. Run /model and choose Freebuild.",
+				"info",
+			);
+			syncStatus(ctx);
+		},
+	});
+
+	pi.registerCommand("freebuild-sponsor", {
+		description: "Open the current Freebuild sponsor",
+		handler: async (_args, ctx) => {
+			await openSponsor(ctx);
+		},
+	});
+
+	pi.registerCommand("freebuild-status", {
+		description: "Show Freebuild license and sponsor status",
+		handler: async (_args, ctx) => {
+			const model = ctx.model
+				? `${ctx.model.provider}/${ctx.model.id}`
+				: "none";
+			const maskedInstall = installId
+				? `${installId.slice(0, 12)}...`
+				: "missing";
+			ctx.ui.notify(
+				`Freebuild: ${licenseKey ? "license saved" : "no license"} | model ${model} | install ${maskedInstall} | broker ${brokerUrl}`,
+				"info",
+			);
+		},
+	});
+
+	pi.registerShortcut("alt+o", {
+		description: "Open the Freebuild sponsor",
+		handler: async (ctx) => {
+			await openSponsor(ctx);
+		},
+	});
+}