gentle-pi 3.7.0 → 4.1.0

package/lib/jobs-view.ts

@@ -0,0 +1,161 @@
+// Background jobs overlay (`/gentle:jobs`): this session's jobs beside the
+// selected job's command, status, output file, and output tail. It shares the
+// Agents overlay geometry and roles so both read as one family, but stays a
+// small standalone view: jobs have no peers, groups, or threads.
+
+import { Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { JobRecord } from "./background-jobs.ts";
+import { formatJobDuration, JOB_GLYPH, jobOutcome } from "./background-jobs-tools.ts";
+import { measureAgentsViewLayout } from "./agents-view-layout.ts";
+import { sanitizeTerminalText } from "./terminal-theme.ts";
+
+export interface JobsViewDeps {
+	theme: { fg(role: string, text: string): string };
+	rows: () => number;
+	/** This session's jobs; the view sorts a copy by activity and recency. */
+	jobs: () => JobRecord[];
+	now: () => number;
+	onStop(job: JobRecord): void;
+	onClose(): void;
+	requestRender(): void;
+}
+
+const ROLE = { FRAME: "border", TITLE: "customMessageLabel", SELECTED: "accent", NAME: "text", META: "dim", KEY: "accent", KEY_TEXT: "dim", EMPTY: "dim" } as const;
+const REFRESH_MS = 1000;
+
+function glyph(job: JobRecord): [string, string] {
+	if (job.status === "running") return [job.kind === "monitor" ? "◉" : "◐", "accent"];
+	if (job.status === "stopped") return ["–", "dim"];
+	if (job.status === "exited" && job.exitCode === 0) return ["✓", "success"];
+	return ["✗", "error"];
+}
+
+const rule = (length: number) => "─".repeat(Math.max(0, length));
+const fit = (text: string, width: number) => {
+	const clipped = truncateToWidth(text, Math.max(0, width), "…");
+	return clipped + " ".repeat(Math.max(0, width - visibleWidth(clipped)));
+};
+const clean = (text: string) => sanitizeTerminalText(text).replace(/\s+/g, " ");
+
+export class JobsView {
+	private readonly deps: JobsViewDeps;
+	private selectedId: string | undefined;
+	private details = false;
+	private listScroll = 0;
+	private closed = false;
+	private readonly timer: ReturnType<typeof setInterval>;
+
+	constructor(deps: JobsViewDeps) {
+		this.deps = deps;
+		// Elapsed time and the output tail move while a job runs.
+		this.timer = setInterval(() => {
+			if (this.deps.jobs().some((job) => job.status === "running")) this.deps.requestRender();
+		}, REFRESH_MS);
+		this.timer.unref?.();
+	}
+
+	dispose(): void {
+		this.closed = true;
+		clearInterval(this.timer);
+	}
+
+	invalidate(): void {}
+
+	handleInput(data: string): void {
+		if (this.closed) return;
+		const jobs = this.orderedJobs();
+		const index = Math.max(0, jobs.findIndex((job) => job.id === this.selected(jobs)?.id));
+		if (data === "q") this.close();
+		else if (matchesKey(data, Key.escape)) {
+			if (this.details) this.details = false;
+			else this.close();
+		} else if (data === "\t" || matchesKey(data, Key.enter)) this.details = !this.details;
+		else if (data === "j" || matchesKey(data, Key.down)) this.selectedId = jobs[Math.min(jobs.length - 1, index + 1)]?.id;
+		else if (data === "k" || matchesKey(data, Key.up)) this.selectedId = jobs[Math.max(0, index - 1)]?.id;
+		else if (data === "s") {
+			const job = this.selected(jobs);
+			if (job?.status === "running") this.deps.onStop(job);
+		} else return;
+		this.deps.requestRender();
+	}
+
+	render(width: number): string[] {
+		const layout = measureAgentsViewLayout(width, this.deps.rows(), this.details);
+		if (layout.width === 0 || layout.height === 0) return [];
+		if (layout.mode === "fallback") return [fit("× Close Jobs", layout.width)];
+		const { theme } = this.deps;
+		const jobs = this.orderedJobs();
+		const selected = this.selected(jobs);
+		const inner = layout.width - 2;
+		const running = jobs.filter((job) => job.status === "running").length;
+		const title = truncateToWidth(`${JOB_GLYPH} Jobs · ${running} running · ${jobs.length - running} finished`, Math.max(0, inner - 4), "…");
+		const top = theme.fg(ROLE.FRAME, "╭─ ") + theme.fg(ROLE.TITLE, title) + theme.fg(ROLE.FRAME, ` ${rule(inner - visibleWidth(title) - 3)}╮`);
+		const list = this.listLines(jobs, selected, layout.listWidth, layout.bodyRows);
+		const detail = selected ? this.detailLines(selected, layout.bodyRows) : [theme.fg(ROLE.EMPTY, "No background jobs in this session."), theme.fg(ROLE.EMPTY, "The agent starts them with bash_background or monitor.")];
+		const bar = theme.fg(ROLE.FRAME, "│");
+		const body: string[] = [];
+		for (let row = 0; row < layout.bodyRows; row += 1) {
+			if (layout.mode === "panes") body.push(`${bar} ${fit(list[row] ?? "", layout.listWidth)} ${bar} ${fit(detail[row] ?? "", layout.threadWidth)}${bar}`);
+			else body.push(`${bar} ${fit((this.details ? detail : list)[row] ?? "", layout.listWidth)} ${bar}`);
+		}
+		const keys = this.keys(selected, layout.mode === "narrow").map(([key, label]) => `${theme.fg(ROLE.KEY, key)} ${theme.fg(ROLE.KEY_TEXT, label)}`).join("   ");
+		return [top, ...body, `${bar} ${fit(keys, inner - 2)} ${bar}`, theme.fg(ROLE.FRAME, `╰${rule(inner)}╯`)];
+	}
+
+	private orderedJobs(): JobRecord[] {
+		return [...this.deps.jobs()].sort((a, b) =>
+			Number(b.status === "running") - Number(a.status === "running") || b.startedAt - a.startedAt);
+	}
+
+	private close(): void {
+		this.deps.onClose();
+	}
+
+	private selected(jobs: JobRecord[]): JobRecord | undefined {
+		const selected = jobs.find((job) => job.id === this.selectedId) ?? jobs[0];
+		this.selectedId = selected?.id;
+		return selected;
+	}
+
+	private elapsed(job: JobRecord): string {
+		return formatJobDuration((job.endedAt ?? this.deps.now()) - job.startedAt);
+	}
+
+	private listLines(jobs: JobRecord[], selected: JobRecord | undefined, width: number, rows: number): string[] {
+		const { theme } = this.deps;
+		if (jobs.length === 0) return [theme.fg(ROLE.EMPTY, "No jobs")];
+		const index = jobs.findIndex((job) => job.id === selected?.id);
+		if (index < this.listScroll) this.listScroll = index;
+		else if (index >= this.listScroll + rows) this.listScroll = index - rows + 1;
+		this.listScroll = Math.max(0, Math.min(this.listScroll, Math.max(0, jobs.length - rows)));
+		return jobs.slice(this.listScroll, this.listScroll + rows).map((job) => {
+			const [mark, role] = glyph(job);
+			const elapsed = this.elapsed(job);
+			const isSelected = job.id === selected?.id;
+			const name = fit(`${isSelected ? "›" : " "} ${mark} ${clean(job.label)}`, Math.max(0, width - visibleWidth(elapsed) - 1));
+			return `${theme.fg(isSelected ? ROLE.SELECTED : role === "accent" ? ROLE.NAME : role, name)} ${theme.fg(ROLE.META, elapsed)}`;
+		});
+	}
+
+	private detailLines(job: JobRecord, rows: number): string[] {
+		const { theme } = this.deps;
+		const head = [
+			theme.fg(ROLE.TITLE, `${clean(job.label)} · ${job.id}`),
+			`${theme.fg(ROLE.META, "Command")} ${clean(job.command)}`,
+			`${theme.fg(ROLE.META, "Status ")} ${clean(jobOutcome(job))} · ${this.elapsed(job)}${job.kind === "monitor" ? ` · ${job.events ?? 0} event${job.events === 1 ? "" : "s"}` : ""}`,
+			`${theme.fg(ROLE.META, "Output ")} ${clean(job.outputPath)}`,
+			"",
+		];
+		const room = Math.max(0, rows - head.length - 1);
+		const tail = job.tail.slice(-room).map((line) => sanitizeTerminalText(line));
+		return [...head, theme.fg(ROLE.META, tail.length > 0 ? "Last output" : "No output yet."), ...tail];
+	}
+
+	private keys(selected: JobRecord | undefined, narrow: boolean): Array<[string, string]> {
+		const keys: Array<[string, string]> = [["↑↓", "move"]];
+		if (narrow && selected) keys.push(["tab", this.details ? "list" : "details"]);
+		if (selected?.status === "running") keys.push(["s", "Stop"]);
+		keys.push(["q", "close"]);
+		return keys;
+	}
+}

package/lib/model-price-ratio.ts

@@ -0,0 +1,83 @@
+// gentle-shell#1731: the orchestrator/worker price ratio is a runtime fact.
+// The harness renders it as one line computed from catalog prices, so the
+// model routes implementation by a number it never has to estimate.
+
+export interface ModelIdentity {
+	provider: string | undefined;
+	id: string;
+}
+
+/** Catalog price in USD per 1M tokens, as Pi's model registry reports it. */
+export interface ModelCost {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+}
+
+export type ModelPriceLookup = (model: ModelIdentity) => ModelCost | undefined;
+
+export type ModelPriceRatio =
+	| { kind: "known"; orchestrator: string; worker: string; input: number; output: number; blended: number }
+	| { kind: "unknown"; reason: string };
+
+function label(model: ModelIdentity): string {
+	return model.provider ? `${model.provider}/${model.id}` : model.id;
+}
+
+function validPrice(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+
+export function computeModelPriceRatio(
+	orchestrator: ModelIdentity | undefined,
+	worker: ModelIdentity | undefined,
+	lookup: ModelPriceLookup,
+): ModelPriceRatio {
+	if (!orchestrator) return { kind: "unknown", reason: "orchestrator model unknown" };
+	if (!worker) return { kind: "unknown", reason: "worker model unknown" };
+	const prices: ModelCost[] = [];
+	for (const model of [orchestrator, worker]) {
+		let cost: ModelCost | undefined;
+		try {
+			cost = lookup(model);
+		} catch {
+			return { kind: "unknown", reason: "price lookup failed" };
+		}
+		if (!cost) return { kind: "unknown", reason: `no catalog price for ${label(model)}` };
+		if (!validPrice(cost.input) || !validPrice(cost.output)) return { kind: "unknown", reason: `zero or invalid price for ${label(model)}` };
+		prices.push(cost);
+	}
+	const [orchestratorCost, workerCost] = prices;
+	const input = orchestratorCost.input / workerCost.input;
+	const output = orchestratorCost.output / workerCost.output;
+	// The blended ratio is the larger of the two. Catalogs usually keep input
+	// and output prices proportional, so both agree; when they diverge, the
+	// session's token mix is unknown up front, and the dimension where the
+	// orchestrator is relatively pricier is the one delegation saves on.
+	return { kind: "known", orchestrator: label(orchestrator), worker: label(worker), input, output, blended: Math.max(input, output) };
+}
+
+// Rounds half up at one decimal; toFixed alone misrounds values
+// such as 2.95 because of their binary representation.
+function times(value: number): string {
+	return `${(Math.round(value * 10) / 10).toFixed(1)}x`;
+}
+
+export function renderModelRoutingLine(ratio: ModelPriceRatio): string {
+	if (ratio.kind === "unknown") return `Model routing: price ratio unknown (${ratio.reason}).`;
+	return `Model routing: orchestrator ${ratio.orchestrator} costs ${times(ratio.blended)} the worker ${ratio.worker} (input ${times(ratio.input)}, output ${times(ratio.output)}).`;
+}
+
+/** The harness fact line. Never throws: any failure renders the unknown line. */
+export function modelRoutingLine(
+	orchestrator: ModelIdentity | undefined,
+	worker: ModelIdentity | undefined,
+	lookup: ModelPriceLookup,
+): string {
+	try {
+		return renderModelRoutingLine(computeModelPriceRatio(orchestrator, worker, lookup));
+	} catch {
+		return renderModelRoutingLine({ kind: "unknown", reason: "price ratio failed" });
+	}
+}

package/lib/model-routing-authority.ts

@@ -63,7 +63,11 @@ export function normalizeRoutingEntry(value: unknown): AgentRoutingEntry | undef
 	}
 	if (!isRecord(value)) return undefined;
 	const model = normalizeModelId(value.model);
-	const thinking = isThinkingLevel(value.thinking) ? value.thinking : undefined;
+	const thinking = isThinkingLevel(value.thinking)
+		? value.thinking
+		: isThinkingLevel(value.effort)
+			? value.effort
+			: undefined;
 	if (!model && !thinking) {
 		return Object.keys(value).length === 0 ? {} : undefined;
 	}

package/lib/nan-provider.ts

@@ -0,0 +1,249 @@
+import * as piAi from "@earendil-works/pi-ai";
+import type { Provider, ProviderStreams, RefreshModelsContext } from "@earendil-works/pi-ai";
+import type { ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+
+export const NAN_PROVIDER_ID = "nan";
+export const NAN_PROVIDER_BASE_URL = "https://api.nan.builders/v1";
+export const NAN_MODELS_TIMEOUT_MS = 3_000;
+
+export interface NanProviderOptions {
+	fetchImpl?: typeof fetch;
+	timeoutMs?: number;
+}
+
+type NanChatModelConfig = Extract<ProviderModelConfig, { type?: "chat" }>;
+
+// Pi requires numeric rates; NaN access is quota-based, so zero avoids inventing per-token pricing.
+const ZERO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+
+// Maintained chat subset from https://nan.builders/docs/models.
+// Decimal bounds conservatively interpret the documented 1M/262K/131K labels.
+// Pi models text/image inputs only; documented audio/video inputs are not advertised.
+// Reasoning shares max_tokens with the answer: 65,536 leaves answer room after a
+// 32,768 reasoning budget; DeepSeek uses NaN's 16,384 floor. Qwen 3.8 retains its
+// published 131K output maximum. The remaining 32,768 caps are configured, not NaN-published limits.
+// Pi requires explicit max mappings to offer that level; a null hides a level Pi would otherwise
+// offer, and missing ordinary levels pass through. Each map exposes exactly the efforts NaN's
+// reasoning contract declares and sends only values NaN accepts.
+// GLM 5.3 / GLM 5.3 Flash: low · medium · high · max, fully controllable and without an off.
+const GLM_THINKING_LEVEL_MAP: NanChatModelConfig["thinkingLevelMap"] = {
+	off: null, minimal: null, xhigh: null, max: "max",
+};
+// Qwen 3.6 and Gemma 4 honor none · minimal · low · medium · high · max as depth controls.
+// DeepSeek V4 Flash, Qwen 3.8 Flash, and MiMo accept the same values while NaN manages their
+// depth itself; none disables reasoning only where NaN honors it.
+const EXTENDED_THINKING_LEVEL_MAP: NanChatModelConfig["thinkingLevelMap"] = {
+	off: "none", xhigh: null, max: "max",
+};
+
+/**
+ * NaN accepts `reasoning_effort` for these models but manages their depth itself, so the selected
+ * level never changes it. Qwen 3.6 and Gemma 4 share the extended map yet honor the level as a
+ * reasoning budget, so the distinction lives here and the shell labels only these three automatic.
+ */
+export const NAN_ADAPTIVE_REASONING_MODEL_IDS: ReadonlySet<string> = new Set([
+	"deepseek-v4-flash", "qwen3.8-flash", "mimo-v2.6-flash",
+]);
+
+export function isNanAdaptiveReasoningModel(model: { provider: string; id: string } | undefined): boolean {
+	return model !== undefined && model.provider === NAN_PROVIDER_ID && NAN_ADAPTIVE_REASONING_MODEL_IDS.has(model.id);
+}
+
+const CHAT_MODELS: NanChatModelConfig[] = ([
+	{
+		id: "glm5.3", name: "GLM 5.3", input: ["text", "image"], contextWindow: 1_000_000,
+		thinkingLevelMap: GLM_THINKING_LEVEL_MAP,
+	},
+	{
+		id: "deepseek-v4-flash", name: "DeepSeek V4 Flash", input: ["text", "image"], contextWindow: 1_000_000,
+		thinkingLevelMap: EXTENDED_THINKING_LEVEL_MAP, maxTokens: 16_384,
+	},
+	{
+		id: "glm5.3-flash", name: "GLM 5.3 Flash", input: ["text", "image"], contextWindow: 1_000_000,
+		thinkingLevelMap: GLM_THINKING_LEVEL_MAP,
+	},
+	{
+		id: "qwen3.8-flash", name: "Qwen 3.8 Flash", input: ["text", "image"], contextWindow: 1_048_576,
+		thinkingLevelMap: EXTENDED_THINKING_LEVEL_MAP, maxTokens: 131_000,
+	},
+	{
+		id: "mimo-v2.6-flash", name: "MiMo V2.6 Flash", input: ["text", "image"], contextWindow: 1_000_000,
+		thinkingLevelMap: EXTENDED_THINKING_LEVEL_MAP,
+	},
+	{
+		id: "gemma4", name: "Gemma 4", input: ["text", "image"], contextWindow: 262_000,
+		thinkingLevelMap: EXTENDED_THINKING_LEVEL_MAP, maxTokens: 65_536,
+	},
+	{
+		id: "qwen3.6", name: "Qwen 3.6", input: ["text", "image"], contextWindow: 262_000,
+		thinkingLevelMap: EXTENDED_THINKING_LEVEL_MAP, maxTokens: 65_536,
+	},
+] satisfies Partial<NanChatModelConfig>[]).map((model) => ({
+	...model,
+	api: "openai-completions",
+	reasoning: true,
+	cost: ZERO_COST,
+	maxTokens: model.maxTokens ?? 32_768,
+}));
+
+// The cold/offline baseline declares documented chat support, not key entitlement.
+// A successful live catalog remains authoritative for the credential that fetched it.
+const OFFLINE_MODELS = CHAT_MODELS;
+
+function cloneModel(model: NanChatModelConfig): NanChatModelConfig {
+	return {
+		...model,
+		input: [...model.input],
+		cost: { ...model.cost },
+		thinkingLevelMap: model.thinkingLevelMap ? { ...model.thinkingLevelMap } : undefined,
+	};
+}
+
+function knownChatModels(ids: readonly string[]): NanChatModelConfig[] {
+	return ids.flatMap((id) => {
+		const known = CHAT_MODELS.find((model) => model.id === id);
+		return known ? [cloneModel(known)] : [];
+	});
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Returns undefined on an unusable response; an empty data array is authoritative. */
+async function fetchLiveModelIds(options: {
+	apiKey?: string;
+	signal: AbortSignal;
+	fetchImpl: typeof fetch;
+	timeoutMs: number;
+}): Promise<string[] | undefined> {
+	const { apiKey, signal, fetchImpl, timeoutMs } = options;
+	if (signal.aborted) return undefined;
+
+	const controller = new AbortController();
+	const abort = () => controller.abort(signal.reason);
+	if (signal.aborted) abort();
+	else signal.addEventListener("abort", abort, { once: true });
+	const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+	try {
+		const headers: Record<string, string> = { Accept: "application/json" };
+		if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+		const response = await fetchImpl(`${NAN_PROVIDER_BASE_URL}/models`, {
+			method: "GET",
+			headers,
+			signal: controller.signal,
+			redirect: "error",
+			cache: "no-store",
+		});
+		if (!response.ok) return undefined;
+
+		const payload: unknown = await response.json();
+		if (!isRecord(payload) || !Array.isArray(payload.data)) return undefined;
+		if (payload.data.length === 0) return [];
+
+		const ids = new Set<string>();
+		for (const row of payload.data) {
+			if (!isRecord(row) || typeof row.id !== "string") continue;
+			const id = row.id.trim();
+			if (id) ids.add(id);
+		}
+		return ids.size > 0 ? [...ids] : undefined;
+	} catch {
+		// Discovery is best-effort. Never log request or response data: it may contain credentials.
+		return undefined;
+	} finally {
+		clearTimeout(timeout);
+		signal.removeEventListener("abort", abort);
+	}
+}
+
+function cloneCatalog(models: readonly NanChatModelConfig[]): NanChatModelConfig[] {
+	return models.map(cloneModel);
+}
+
+/** Native auth belongs to the provider; Pi persists only a successful login result. */
+export function createNanProviderConfig(options: NanProviderOptions = {}): Provider<"openai-completions"> {
+	const config = createCatalogConfig(options);
+	// Pi's extension loader aliases the bare root to compat, which exposes this
+	// host-owned lazy API factory. Do not import an SDK implementation subpath.
+	const api = piAi.lazyApi(async () => {
+		const runtime = piAi as typeof piAi & { openAICompletionsApi?: () => ProviderStreams };
+		if (!runtime.openAICompletionsApi) throw new Error("NaN requires Pi's OpenAI completions API factory");
+		return runtime.openAICompletionsApi();
+	});
+	return {
+		id: NAN_PROVIDER_ID,
+		name: "NaN",
+		baseUrl: NAN_PROVIDER_BASE_URL,
+		auth: { apiKey: {
+			name: "NaN API key",
+			async login(interaction) {
+				interaction.signal.throwIfAborted();
+				const entered = await interaction.prompt({
+					type: "secret", message: "Enter API key", signal: interaction.signal,
+				});
+				interaction.signal.throwIfAborted();
+				const key = entered.trim();
+				if (!key) throw new Error("NaN requires a non-empty API key");
+				return { type: "api_key", key };
+			},
+			async resolve({ ctx, credential, signal }) {
+				signal.throwIfAborted();
+				const stored = credential?.key?.trim();
+				const key = stored || (await ctx.env("NAN_API_KEY"))?.trim();
+				signal.throwIfAborted();
+				return key ? { auth: { apiKey: key }, source: stored ? "API key" : "NAN_API_KEY" } : undefined;
+			},
+		} },
+		getModels: () => config.getModels().map((model) => ({
+			...cloneModel(model), provider: NAN_PROVIDER_ID,
+			baseUrl: NAN_PROVIDER_BASE_URL, api: "openai-completions" as const,
+		})),
+		refreshModels: (context) => config.refreshModels(context),
+		stream: api.stream,
+		streamSimple: api.streamSimple,
+	};
+}
+
+function createCatalogConfig(options: NanProviderOptions = {}): {
+	getModels(): NanChatModelConfig[];
+	refreshModels(context: RefreshModelsContext): Promise<void>;
+} {
+	let catalog = cloneCatalog(OFFLINE_MODELS);
+	let catalogKey: string | undefined;
+	let credentialRevision = 0;
+	const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+
+	return {
+		// One source of truth lets Pi snapshot the new catalog inside publish.update.
+		getModels: () => cloneCatalog(catalog),
+		refreshModels: async (context: RefreshModelsContext) => {
+			const apiKey = context.credential?.type === "api_key" ? context.credential.key : undefined;
+			if (apiKey !== catalogKey) {
+				// A live catalog is authoritative only for the credential that discovered it.
+				catalogKey = apiKey;
+				credentialRevision++;
+				catalog = cloneCatalog(OFFLINE_MODELS);
+			}
+			const revision = credentialRevision;
+			if (!context.allowNetwork || context.signal.aborted || typeof fetchImpl !== "function") {
+				return;
+			}
+
+			const ids = await fetchLiveModelIds({
+				apiKey,
+				signal: context.signal,
+				fetchImpl,
+				timeoutMs: options.timeoutMs ?? NAN_MODELS_TIMEOUT_MS,
+			});
+			if (revision !== credentialRevision || ids === undefined || context.signal.aborted) {
+				return;
+			}
+
+			await context.publish({ update: () => {
+				if (revision === credentialRevision && !context.signal.aborted) catalog = knownChatModels(ids);
+			} });
+		},
+	};
+}