@xzzpig/pi-starline 0.5.1 → 0.7.1

package/extensions/starline/pill-actions.ts

@@ -0,0 +1,590 @@
+/**
+ * What clicking a pill does.
+ *
+ * One table, keyed by segment. A segment with no entry stays a label:
+ * `handleMouse` returns undefined for it and the click falls through to Pi, so an
+ * inert pill swallows nothing. Every entry also answers to a `/starline`
+ * subcommand of the same name, which is what makes the keyboard path real rather
+ * than aspirational.
+ *
+ * An action receives the anchor of the pill it was called for, so anything it
+ * shows can be placed against that pill. The bubble itself lives in
+ * `pill-bubble.ts` and is shared: this file only decides what goes in it.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { activeContextSnapshot } from "./context-live";
+import { formatCount } from "./format";
+import { activeGitStatus } from "./git-live";
+import {
+	cycleThinkingLevel,
+	readPendingMessages,
+	readThinkingLevels,
+	setThinkingLevel,
+} from "./live-session";
+import { externalPillAction } from "./pill-api";
+import {
+	type PillAnchor,
+	type PillBubbleContent,
+	type PillBubbleHandle,
+	showPillBubble,
+} from "./pill-bubble";
+import { PILL_SEGMENT_VARIABLES } from "./pill-config";
+import { type FleetSnapshot, getActiveSubagentFleet } from "./subagent-fleet";
+
+/** What an action gets: the session, and where the pill is if a click found it. */
+export type PillActionContext = {
+	ctx: ExtensionContext;
+	/**
+	 * Geometry and colours of the pill this action belongs to. Absent when the
+	 * command path runs while the pill is not on screen (text footer, or the
+	 * segment removed from `pill.segments`); bubbles then fall back to centred.
+	 */
+	pill?: PillAnchor;
+	/**
+	 * How the action was reached. A click can offer a choice in the bubble; the
+	 * `/starline` command has no pointer to make one with, so an action that
+	 * offers choices does something direct instead.
+	 */
+	via: "click" | "command";
+};
+
+export type PillAction = (context: PillActionContext) => void | Promise<void>;
+
+/**
+ * Whether the session is holding messages for the running turn.
+ *
+ * The public surface is a boolean. Guarded rather than assumed: a build without
+ * it, or a context that has gone stale after a session swap, must leave the pill
+ * out instead of taking the footer's render down with it.
+ */
+export function hasQueuedMessages(ctx: ExtensionContext): boolean {
+	try {
+		const read = (ctx as ExtensionContext & { hasPendingMessages?: () => boolean })
+			.hasPendingMessages;
+		return typeof read === "function" && read.call(ctx) === true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * The queue pill's text: the icon and how many messages wait (`<icon> 3`). The
+ * count needs the live session; without it the pill still says `queued`. With no
+ * icon (ascii mode) the number keeps its word, `3 queued`, so a bare digit never
+ * stands in the bar unexplained.
+ */
+export function queuedSegmentText(ctx: ExtensionContext, icon = ""): string {
+	if (!hasQueuedMessages(ctx)) return "";
+	const pending = readPendingMessages();
+	const count = pending ? pending.steering.length + pending.followUp.length : 0;
+	if (count > 0) return icon ? `${icon} ${count}` : `${count} queued`;
+	return icon ? `${icon} queued` : "queued";
+}
+
+/** How often an open bubble whose numbers move re-reads them. */
+const LIVE_BUBBLE_INTERVAL_MS = 1_000;
+
+/**
+ * Re-run `tick` every second while `handle` is open, then stop. The timer never
+ * keeps Pi alive on its own, and stops itself if the bubble has already gone.
+ */
+function whileOpen(handle: PillBubbleHandle, tick: () => void): void {
+	if (!handle.isOpen()) return;
+	const timer = setInterval(() => {
+		if (!handle.isOpen()) {
+			clearInterval(timer);
+			return;
+		}
+		tick();
+	}, LIVE_BUBBLE_INTERVAL_MS);
+	timer.unref?.();
+	handle.onClose(() => clearInterval(timer));
+}
+
+/**
+ * Cap on listed messages. More than a few turns a bubble into a wall, and the
+ * count in the title already says how many there are.
+ */
+const MAX_LISTED_MESSAGES = 3;
+/** Roughly what fits in the widest bubble, bullet included, before wrapping. */
+const MAX_MESSAGE_COLUMNS = 58;
+
+function oneLine(message: string): string {
+	const collapsed = message.replace(/\s+/gu, " ").trim();
+	return truncateToWidth(collapsed, MAX_MESSAGE_COLUMNS, "…");
+}
+
+/**
+ * What the queue bubble says: the count and the messages when the live session
+ * is readable, and the behaviour when it is not.
+ */
+export function queuedBubbleContent(): PillBubbleContent {
+	const pending = readPendingMessages();
+	if (!pending) {
+		return {
+			title: "Queued messages",
+			body: [
+				"Messages you send while the agent is working wait until the current turn ends, then get delivered.",
+				"This build of Pi does not expose them to the extension, so the count and the text are unknown.",
+			],
+			hint: "esc to close",
+		};
+	}
+
+	const messages = [...pending.steering, ...pending.followUp];
+	// The bubble stays open while the turn ends and the queue drains under it.
+	if (messages.length === 0) {
+		return { title: "Queued messages", body: ["Nothing is queued."], hint: "esc to close" };
+	}
+	const listed = messages.slice(0, MAX_LISTED_MESSAGES).map((message) => `· ${oneLine(message)}`);
+	if (messages.length > listed.length) {
+		listed.push(`· +${messages.length - listed.length} more`);
+	}
+	return {
+		title: `${messages.length} message${messages.length === 1 ? "" : "s"} queued`,
+		body: listed,
+		hint: "esc to close",
+	};
+}
+
+function showQueuedMessages({ ctx, pill }: PillActionContext): void {
+	if (!hasQueuedMessages(ctx)) {
+		// The pill only exists while something is queued; the command does not.
+		if (ctx.hasUI) ctx.ui.notify("No messages are queued", "info");
+		return;
+	}
+	// Live: the queue drains as the turn ends, and new messages join it.
+	const handle = showPillBubble(ctx, queuedBubbleContent, pill);
+	whileOpen(handle, () => handle.refresh());
+}
+
+function thinkingUnavailable(ctx: ExtensionContext): PillBubbleContent {
+	const current = ctx.thinkingLevel ?? "";
+	return {
+		title: "Thinking",
+		body: current
+			? [`Current level: ${current}.`, "This session cannot change it from here."]
+			: ["This model has no thinking level to change."],
+		hint: "esc to close",
+	};
+}
+
+/**
+ * What the thinking pill's bubble offers: every level the model supports, the
+ * current one marked and the others clickable. Picking one closes the bubble;
+ * the footer re-renders from `thinking_level_select`, so the pill itself is the
+ * confirmation.
+ */
+export function thinkingPickerContent(ctx: ExtensionContext): PillBubbleContent {
+	const read = readThinkingLevels();
+	if (!read) return thinkingUnavailable(ctx);
+	return {
+		title: "Thinking",
+		body: read.levels.map((level) =>
+			// Every level is a target, the current one too: the bubble opens with it
+			// selected, so ↑/↓ move from where you are. Choosing it changes nothing.
+			level === read.current
+				? { text: `● ${level}`, current: true, onSelect: () => {} }
+				: {
+						text: `○ ${level}`,
+						onSelect: () => {
+							if (!setThinkingLevel(level) && ctx.hasUI) {
+								ctx.ui.notify(`Could not switch thinking to ${level}`, "error");
+							}
+						},
+					},
+		),
+		hint: "↑↓ enter · click · esc",
+	};
+}
+
+/**
+ * A click opens the level list; it changes nothing until a level is picked, so
+ * looking is free. The command has no pointer to pick with, so it steps to the
+ * next level and says where it landed.
+ */
+function showThinkingLevel({ ctx, pill, via }: PillActionContext): void {
+	if (via === "click") {
+		showPillBubble(ctx, thinkingPickerContent(ctx), pill);
+		return;
+	}
+	const cycled = cycleThinkingLevel();
+	showPillBubble(
+		ctx,
+		cycled
+			? { title: "Thinking", body: [`${cycled.from} → ${cycled.to}`], hint: "esc to close" }
+			: thinkingUnavailable(ctx),
+		pill,
+	);
+}
+
+/** The parts of a Pi model the picker reads. */
+export type PickableModel = { provider: string; id: string; name?: string };
+
+/** A model offered by the picker, with the thinking level its scope pins, if any. */
+export type ModelChoice = { model: PickableModel; thinkingLevel?: string };
+
+/**
+ * Switch the session's model. Registered by the extension entry, which holds `pi`;
+ * an action only gets the context, and `setModel` is not on it.
+ */
+export type ModelSwitcher = (choice: ModelChoice) => Promise<boolean>;
+
+let modelSwitcher: ModelSwitcher | undefined;
+
+export function setModelSwitcher(switcher: ModelSwitcher | undefined): void {
+	modelSwitcher = switcher;
+}
+
+/** Without a model scope the picker falls back to the whole catalogue, capped. */
+const MAX_UNSCOPED_MODELS = 8;
+
+const sameModel = (a: PickableModel | undefined, b: PickableModel | undefined) =>
+	a !== undefined && b !== undefined && a.provider === b.provider && a.id === b.id;
+
+const modelLabel = (model: PickableModel) => `${model.id} · ${model.provider}`;
+
+/**
+ * What the model picker offers: the session's scoped models — the ones ctrl+p
+ * cycles, from `enabledModels` or `--models` — or, with no scope, the available
+ * models with auth, capped so the bubble stays a bubble. The current model is
+ * always in the list.
+ */
+export function modelChoices(ctx: ExtensionContext): { choices: ModelChoice[]; more: number } {
+	const current = ctx.model as PickableModel | undefined;
+	const scoped = Array.isArray(ctx.scopedModels) ? ctx.scopedModels : [];
+	if (scoped.length > 0) {
+		return {
+			choices: scoped.map((entry) => ({
+				model: entry.model as PickableModel,
+				thinkingLevel: entry.thinkingLevel,
+			})),
+			more: 0,
+		};
+	}
+	let available: PickableModel[] = [];
+	try {
+		available = (ctx.modelRegistry?.getAvailable() ?? []) as PickableModel[];
+	} catch {
+		available = [];
+	}
+	const listed = available.slice(0, MAX_UNSCOPED_MODELS);
+	// Counted before the current model is put in front: it may not be one of the
+	// available ones at all, and it must not hide one that is.
+	const more = Math.max(0, available.length - listed.length);
+	if (current && !listed.some((model) => sameModel(model, current))) listed.unshift(current);
+	return { choices: listed.map((model) => ({ model })), more };
+}
+
+async function switchModel(ctx: ExtensionContext, choice: ModelChoice): Promise<boolean> {
+	let switched = false;
+	try {
+		switched = (await modelSwitcher?.(choice)) === true;
+	} catch {
+		switched = false;
+	}
+	if (!switched && ctx.hasUI) {
+		ctx.ui.notify(`Could not switch to ${modelLabel(choice.model)}`, "error");
+	}
+	return switched;
+}
+
+/** The model pill's bubble: every choice, the current one marked. */
+export function modelPickerContent(ctx: ExtensionContext): PillBubbleContent {
+	const { choices, more } = modelChoices(ctx);
+	const current = ctx.model as PickableModel | undefined;
+	if (choices.length === 0 || !modelSwitcher) {
+		return {
+			title: "Model",
+			body: [
+				current ? `Current model: ${modelLabel(current)}.` : "No model is selected.",
+				"Use /model to pick one.",
+			],
+			hint: "esc to close",
+		};
+	}
+	// The current model is a target too, opened selected, so ↑/↓ start from it.
+	const body: PillBubbleContent["body"] = choices.map((choice) =>
+		sameModel(choice.model, current)
+			? { text: `● ${modelLabel(choice.model)}`, current: true, onSelect: () => {} }
+			: {
+					text: `○ ${modelLabel(choice.model)}`,
+					onSelect: () => void switchModel(ctx, choice),
+				},
+	);
+	if (more > 0) body.push(`+${more} more in /model`);
+	return { title: "Model", body, hint: "↑↓ enter · click · /model for all" };
+}
+
+/**
+ * A click opens the picker. The command steps to the next choice, the same way
+ * ctrl+p cycles scoped models, and reports where it landed.
+ */
+async function showModels({ ctx, pill, via }: PillActionContext): Promise<void> {
+	if (via === "click") {
+		showPillBubble(ctx, modelPickerContent(ctx), pill);
+		return;
+	}
+	const { choices } = modelChoices(ctx);
+	const current = ctx.model as PickableModel | undefined;
+	const index = choices.findIndex((choice) => sameModel(choice.model, current));
+	const next = choices[(index + 1) % Math.max(1, choices.length)];
+	if (!next || choices.length < 2 || !(await switchModel(ctx, next))) {
+		showPillBubble(ctx, modelPickerContent(ctx), pill);
+		return;
+	}
+	showPillBubble(
+		ctx,
+		{
+			title: "Model",
+			body: [`${current ? current.id : "none"} → ${next.model.id}`],
+			hint: "esc to close",
+		},
+		pill,
+	);
+}
+
+/** `45s`, `3m 12s`, `1h 05m`: what a glance at a running agent needs. */
+export function formatElapsed(milliseconds: number): string {
+	const seconds = Math.max(0, Math.floor(milliseconds / 1000));
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m ${String(seconds % 60).padStart(2, "0")}s`;
+	return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, "0")}m`;
+}
+
+function formatTokens(tokens: number): string {
+	return tokens >= 1000 ? `${Math.round(tokens / 1000)}k tok` : `${tokens} tok`;
+}
+
+/**
+ * One line per running agent: who, on what model, for how long, at what cost.
+ * The model's provider prefix is dropped; the bubble is narrow and the name is
+ * what tells two runs apart.
+ */
+export function subagentsBubbleContent(fleet: FleetSnapshot, now = Date.now()): PillBubbleContent {
+	const listed = fleet.entries.map((entry) => {
+		const name = entry.role ? `${entry.role} (${entry.agent})` : entry.agent;
+		const parts = [name];
+		if (entry.model) parts.push(entry.model.split("/").at(-1) ?? entry.model);
+		parts.push(formatElapsed(now - entry.startedAt));
+		if (entry.tokens > 0) parts.push(formatTokens(entry.tokens));
+		return `· ${truncateToWidth(parts.join(" · "), MAX_MESSAGE_COLUMNS, "…")}`;
+	});
+	const unlisted = Math.max(fleet.omitted, fleet.totalActive - fleet.entries.length);
+	if (unlisted > 0) listed.push(`· +${unlisted} more`);
+	const total = fleet.totalActive;
+	return {
+		title: total > 0 ? `${total} subagent${total === 1 ? "" : "s"} running` : "Subagents",
+		body: total > 0 ? listed : ["Nothing is running."],
+		hint: "/subagents-fleet for details · esc to close",
+	};
+}
+
+/** How long a click waits for fresh numbers before showing the ones it has. */
+const FLEET_FETCH_TIMEOUT_MS = 400;
+
+/**
+ * Ask pi-subagents for the current fleet, then show it. The pill's count may be
+ * a moment old and the elapsed times always are, so the bubble asks again; a
+ * slow answer falls back to the last one rather than keeping the click waiting.
+ */
+async function showSubagents({ ctx, pill }: PillActionContext): Promise<void> {
+	const fleet = getActiveSubagentFleet();
+	if (!fleet) return;
+	const fresh = await fleet.fetch(FLEET_FETCH_TIMEOUT_MS);
+	if (!fresh && !fleet.available()) {
+		if (ctx.hasUI) ctx.ui.notify("pi-subagents is not installed or not answering", "info");
+		return;
+	}
+	// Live: elapsed time and tokens move every second, and runs come and go. Each
+	// tick asks pi-subagents again; the content reads whatever the last answer was.
+	const handle = showPillBubble(ctx, () => subagentsBubbleContent(fleet.snapshot()), pill);
+	let asking = false;
+	whileOpen(handle, () => {
+		// A slow answer skips a tick rather than stacking requests behind it.
+		if (asking) return;
+		asking = true;
+		void fleet.fetch(LIVE_BUBBLE_INTERVAL_MS).then(() => {
+			asking = false;
+			handle.refresh();
+		});
+	});
+}
+
+/**
+ * What the context pill says when clicked: the numbers the bar has no room for.
+ *
+ * The pill keeps the percentage; the window, the tokens used, the session's
+ * in/out counts and the cache rate are all here. Same source as the pill, so the
+ * two cannot disagree while a turn streams.
+ */
+export function contextBubbleContent(): PillBubbleContent {
+	const snapshot = activeContextSnapshot();
+	if (!snapshot) {
+		return { title: "Context", body: ["Nothing has been sent yet."], hint: "esc to close" };
+	}
+
+	const body: string[] = [];
+	const percent =
+		snapshot.percent === undefined || !Number.isFinite(snapshot.percent)
+			? undefined
+			: Math.max(0, Math.min(100, Math.round(snapshot.percent)));
+	if (snapshot.contextWindow) {
+		const windowLabel = formatCount(snapshot.contextWindow);
+		const used = percent === undefined ? `window ${windowLabel}` : `${percent}% of ${windowLabel}`;
+		body.push(
+			snapshot.tokens === undefined ? used : `${used} · ${formatCount(snapshot.tokens)} used`,
+		);
+	}
+	if (snapshot.tokenLabel) body.push(`session ${snapshot.tokenLabel}`);
+	if (snapshot.cacheLabel) body.push(`cache ${snapshot.cacheLabel}`);
+
+	const title = percent === undefined ? "Context" : `${percent}% context`;
+	return {
+		title,
+		body: body.length > 0 ? body : ["No usage yet."],
+		hint: "esc to close",
+	};
+}
+
+function showContext({ ctx, pill }: PillActionContext): void {
+	if (!activeContextSnapshot()) {
+		if (ctx.hasUI) ctx.ui.notify("No context usage in this session", "info");
+		return;
+	}
+	// Live: tokens grow while a turn streams, and the footer pushes a new
+	// snapshot every render.
+	const handle = showPillBubble(ctx, contextBubbleContent, pill);
+	whileOpen(handle, () => handle.refresh());
+}
+
+/** How many changed paths the bubble lists before summarising the rest. */
+const MAX_LISTED_CHANGES = 12;
+/** The order the bubble groups changes in: what is staged first, then the rest. */
+const CHANGE_ORDER = ["M", "A", "R", "T", "D", "U", "?"];
+
+function changeLabel(code: string): string {
+	switch (code) {
+		case "?":
+			return "untracked";
+		case "U":
+			return "conflicted";
+		case "A":
+			return "added";
+		case "R":
+			return "renamed";
+		case "D":
+			return "deleted";
+		case "T":
+			return "type changed";
+		default:
+			return "modified";
+	}
+}
+
+/**
+ * What the git pill says when clicked: the branch, what is ahead/behind, and the
+ * changed paths. Read-only on purpose — there is no branch switch here and no
+ * staging, because an agent may be running in the same tree.
+ */
+export function gitBubbleContent(): PillBubbleContent {
+	const status = activeGitStatus();
+	if (!status) {
+		return { title: "Git", body: ["No repository in this project."], hint: "esc to close" };
+	}
+
+	const body: string[] = [];
+	if (status.gitStateLabel) body.push(`Operation: ${status.gitStateLabel}`);
+	if (status.ahead > 0 || status.behind > 0) {
+		const parts: string[] = [];
+		if (status.ahead > 0) parts.push(`${status.ahead} ahead`);
+		if (status.behind > 0) parts.push(`${status.behind} behind`);
+		body.push(parts.join(", "));
+	}
+	if (status.stashed > 0) body.push(`${status.stashed} stash${status.stashed === 1 ? "" : "es"}`);
+
+	const changes = [...status.changes].sort(
+		(a, b) => CHANGE_ORDER.indexOf(a.code) - CHANGE_ORDER.indexOf(b.code),
+	);
+	for (const change of changes.slice(0, MAX_LISTED_CHANGES)) {
+		// The word rather than the porcelain letter: `?` alone is unreadable and
+		// the bubble has room for one small label per line.
+		body.push(
+			`${changeLabel(change.code)} · ${truncateToWidth(change.path, MAX_MESSAGE_COLUMNS, "…")}`,
+		);
+	}
+	if (changes.length > MAX_LISTED_CHANGES) {
+		body.push(`+${changes.length - MAX_LISTED_CHANGES} more`);
+	}
+	if (changes.length === 0 && body.length === 0) {
+		body.push("Working tree clean.");
+	}
+
+	// A detached HEAD has no branch to name it by, and the pill shows `HEAD` too.
+	const name = status.branch ?? (status.commit?.oid ? "HEAD" : "Git");
+	return {
+		title: changes.length > 0 ? `${name} · ${changes.length} changed` : name,
+		body,
+		hint: changes.length > 0 ? "read-only · esc to close" : "esc to close",
+	};
+}
+
+function showGitChanges({ ctx, pill }: PillActionContext): void {
+	const status = activeGitStatus();
+	if (!status) {
+		if (ctx.hasUI) ctx.ui.notify("No git repository in this project", "info");
+		return;
+	}
+	// Live while open: the agent may touch files, and the next refresh re-reads
+	// them. Nothing here writes.
+	const handle = showPillBubble(ctx, gitBubbleContent, pill);
+	whileOpen(handle, () => handle.refresh());
+}
+
+/**
+ * Segment key → action. Segments with no entry are labels: a click on one is not
+ * handled, so nothing is swallowed.
+ */
+export const PILL_ACTIONS: Readonly<Partial<Record<string, PillAction>>> = {
+	context: showContext,
+	git: showGitChanges,
+	model: showModels,
+	queue: showQueuedMessages,
+	subagents: showSubagents,
+	thinking: showThinkingLevel,
+};
+
+/**
+ * The action for a pill span's key.
+ *
+ * A segment key Starline owns (a builtin segment) wins over a bridge, so a status
+ * cannot hijack `queue`. Everything else is looked up in the published API, which
+ * is how `extensionStatus:<key>` pills become clickable. No entry anywhere means
+ * the pill is a label and the click falls through.
+ */
+export function pillActionFor(key: string): PillAction | undefined {
+	if (key in PILL_SEGMENT_VARIABLES) return PILL_ACTIONS[key];
+	return externalPillAction(key);
+}
+
+/**
+ * Run an action from the mouse or from `/starline`, swallowing failure: a
+ * throwing action must not take down the render loop that dispatched the click,
+ * and the keyboard path is still available.
+ */
+export function runPillAction(
+	action: PillAction,
+	ctx: ExtensionContext,
+	pill?: PillAnchor,
+	via: PillActionContext["via"] = "click",
+): void {
+	try {
+		const pending = action({ ctx, pill, via });
+		if (pending) void pending.catch(() => {});
+	} catch {
+		// Nothing to report: the action's own guards are what keep this rare.
+	}
+}

package/extensions/starline/pill-anchors.ts

@@ -0,0 +1,26 @@
+/**
+ * The last anchors the footer rendered, so the keyboard path can point a bubble
+ * at the same pill a click would have hit.
+ *
+ * A module-level singleton like `working-indicator.ts`: there is one footer per
+ * session, it is the only writer, and actions only need "where is the pill for
+ * this segment right now". Renders happen at several widths while the layout
+ * measures, so the value is best-effort by design; the click path does not use it
+ * (it has the exact span that was hit).
+ */
+
+import type { PillAnchor } from "./pill-bubble";
+
+let anchors = new Map<string, PillAnchor>();
+
+export function setPillAnchors(next: ReadonlyMap<string, PillAnchor>): void {
+	anchors = new Map(next);
+}
+
+export function getPillAnchor(key: string): PillAnchor | undefined {
+	return anchors.get(key);
+}
+
+export function clearPillAnchors(): void {
+	anchors = new Map();
+}

package/extensions/starline/pill-api.ts

@@ -0,0 +1,80 @@
+/**
+ * The bridge other extensions use to make their pill clickable and to open the
+ * same speech bubble Starline uses.
+ *
+ * Starline renders other extensions' pills from `ctx.ui.setStatus()`; this is the
+ * other half: the owning extension says what a click means. A `pi-balance` pill
+ * can open a bubble with its 5h/7d numbers, a `pi-subagents` pill can list its
+ * runs, and neither has to render or position anything.
+ *
+ * The handshake is a global symbol rather than an import, for the same reason
+ * `@xzzpig/pi-mouse-events` publishes one: an extension cannot depend on a
+ * package Starline may be loaded twice from, and load order is not guaranteed.
+ * Register from a `session_start` handler, which runs after every extension in the
+ * process has been loaded; `/reload` re-runs it, so re-registering there is also
+ * what keeps the bridge alive across a reload.
+ *
+ *     const api = globalThis[Symbol.for("pi-starline.pill-api.v1")];
+ *     api?.register("pi-balance", ({ ctx, pill }) => {
+ *       api.showBubble(ctx, { title: "Balance", body: ["5h: 42%", "7d: 12%"] }, pill);
+ *     });
+ *
+ * The same action is reachable from the keyboard as `/starline <key>`. Types for
+ * other extensions are in `types/pill-api.d.ts`; the guide is `docs/pill-api.md`.
+ */
+
+import type { PillApi, PillApiAction } from "../../types/pill-api";
+import { showPillBubble } from "./pill-bubble";
+
+export const PILL_API_SYMBOL = Symbol.for("pi-starline.pill-api.v1");
+
+// The published shapes: `types/pill-api.d.ts` is what other extensions compile
+// against, so it is also what this file implements.
+export type {
+	PillAnchor,
+	PillApi,
+	PillApiAction,
+	PillApiContext,
+	PillBubbleContent,
+	PillBubbleHandle,
+	PillBubbleLine,
+	PillBubbleSource,
+} from "../../types/pill-api";
+
+/**
+ * One action per key: a second registration replaces the first, which is what a
+ * `/reload` of the owning extension does. The disposer only removes its own
+ * action, so a stale handle cannot take a newer bridge down with it.
+ */
+const externalActions = new Map<string, PillApiAction>();
+
+export function registerExternalPillAction(key: string, action: PillApiAction): () => void {
+	const name = key.trim();
+	if (!name) return () => {};
+	externalActions.set(name, action);
+	return () => {
+		if (externalActions.get(name) === action) externalActions.delete(name);
+	};
+}
+
+export function externalPillAction(key: string): PillApiAction | undefined {
+	return externalActions.get(key);
+}
+
+/**
+ * Publish the API on `globalThis`, replacing any earlier object.
+ *
+ * The newest Starline wins. This runs when the extension loads, which is before
+ * any `session_start`, so bridges always register on the object published by the
+ * Starline that is actually running. Keeping an older object instead would, after
+ * a `/reload` that re-imports this module, leave bridges registering into the
+ * previous module's registry while the new footer reads its own.
+ */
+export function publishPillApi(): void {
+	const api: PillApi = {
+		version: 1,
+		register: registerExternalPillAction,
+		showBubble: (ctx, content, pill) => showPillBubble(ctx, content, pill),
+	};
+	(globalThis as Record<PropertyKey, unknown>)[PILL_API_SYMBOL] = api;
+}