@oh-my-pi/pi-ai 18.2.2 → 18.2.4

package/src/judgment/text.ts

@@ -0,0 +1,309 @@
+/**
+ * Text bridge: answers {@link Questions} with any model that completes text.
+ *
+ * Questions render into one system prompt asking for keyword answers (an
+ * option label, `yes`/`no`, or a level number); the state is the user message,
+ * so the question part stays byte-identical across calls and prompt caches
+ * hit. Several questions batch into a single completion answered one line per
+ * question id. Answers are one-hot: a parsed keyword yields probability 1 and
+ * confidence 1, since a text completion carries no distribution.
+ *
+ * The {@link TextBackend} decides *how* text is completed — a chat model via
+ * {@link chatTextBackend}, or an on-device worker — so this file never
+ * depends on chat transports.
+ */
+import { escapeXmlAttribute, escapeXmlText, prompt } from "@oh-my-pi/pi-utils";
+import { YAML } from "bun";
+import type { Usage } from "../types";
+import textJudgeRetryTemplate from "./text-judge-retry.md" with { type: "text" };
+import textJudgeStateTemplate from "./text-judge-state.md" with { type: "text" };
+import textJudgeTemplate from "./text-judge.md" with { type: "text" };
+import {
+	type Answer,
+	type Judge,
+	type JudgeOptions,
+	type JudgmentRequest,
+	type JudgmentResult,
+	JudgmentParseError,
+	type JudgmentState,
+	type JsonValue,
+	type Question,
+	type Questions,
+	tokenUsage,
+} from "./types";
+
+export interface TextPrompt {
+	system: string;
+	user: string;
+	/** Format-correction attempt; chat backends may enforce tool suppression on the wire. */
+	retry?: boolean;
+}
+
+export interface TextCompletion {
+	text: string;
+	/** Omitted by backends that do not meter tokens (on-device workers). */
+	usage?: Usage;
+}
+
+/** Completes a rendered judgment prompt; identifies itself for usage attribution. */
+export interface TextBackend {
+	readonly api: string;
+	readonly provider: string;
+	readonly model: string;
+	/** State guard for agent-tuned chat models; on-device classifier workers may disable it. */
+	readonly guardState?: boolean;
+	/** Format-correction retries after a completion cannot be parsed. */
+	readonly parseRetries?: number;
+	complete(prompt: TextPrompt, options: JudgeOptions): Promise<TextCompletion>;
+}
+
+interface RenderedQuestion {
+	id: string;
+	instructions: string;
+	options?: { label: string; description: string | null }[];
+	levels?: { index: number; description: string }[];
+	yesno?: boolean;
+	yes?: string;
+	no?: string;
+}
+
+const XML_TAG_NAME = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
+
+function isJsonArray(value: JudgmentState): value is readonly JsonValue[] {
+	return Array.isArray(value);
+}
+
+/** Render judgment state as top-level XML fields; nested values use block YAML. */
+export function renderJudgmentState(state: JudgmentState): string {
+	if (typeof state !== "object" || state === null || isJsonArray(state)) {
+		return renderStateField("state", state);
+	}
+	const fields: string[] = [];
+	for (const key in state) {
+		if (!Object.hasOwn(state, key)) continue;
+		fields.push(renderStateField(key, state[key]));
+	}
+	return fields.length > 0 ? fields.join("\n") : "<state>{}</state>";
+}
+
+function renderStateField(key: string, value: JsonValue): string {
+	const validTag = XML_TAG_NAME.test(key);
+	const open = validTag ? `<${key}>` : `<field name="${escapeXmlAttribute(key)}">`;
+	const close = validTag ? `</${key}>` : "</field>";
+	if (typeof value !== "object" || value === null) {
+		return `${open}${escapeXmlText(value === null ? "null" : String(value))}${close}`;
+	}
+	const yaml = YAML.stringify(value, null, 2).trimEnd();
+	return `${open}\n${escapeXmlText(yaml)}\n${close}`;
+}
+
+/**
+ * Render a request: the system prompt carries the preamble and question
+ * definitions (constant across states, so prompt caches hit); the user message
+ * carries XML-field state followed by the answer-format cue. Small models act
+ * on a bare request (answer it, emit tool calls) instead of classifying it —
+ * explicit tags and the trailing cue keep them on task.
+ */
+export function renderJudgmentPrompt(request: JudgmentRequest, options: { guardState?: boolean } = {}): TextPrompt {
+	const questions: RenderedQuestion[] = [];
+	for (const id in request.questions) {
+		const question = request.questions[id];
+		const rendered: RenderedQuestion = { id, instructions: question.instructions };
+		switch (question.type) {
+			case "choice": {
+				const options: RenderedQuestion["options"] = [];
+				for (const label in question.criteria) options.push({ label, description: question.criteria[label] });
+				rendered.options = options;
+				break;
+			}
+			case "score":
+				rendered.levels = question.criteria.map((description, index) => ({ index, description }));
+				break;
+			case "noul":
+				rendered.yesno = true;
+				rendered.yes = question.criteria?.true;
+				rendered.no = question.criteria?.false;
+				break;
+		}
+		questions.push(rendered);
+	}
+	const multi = questions.length > 1;
+	const guardState = options.guardState !== false;
+	return {
+		system: prompt.render(textJudgeTemplate, { questions, multi, guardState }),
+		user: prompt.render(textJudgeStateTemplate, {
+			...questions[0],
+			guardState,
+			multi,
+			state: renderJudgmentState(request.state),
+		}),
+	};
+}
+
+const WORD = /[\p{L}\p{N}_]/u;
+
+/** Index of the earliest whole-word, case-insensitive occurrence of `needle` in `text`, or -1. */
+function indexOfWord(text: string, needle: string): number {
+	const lower = text.toLowerCase();
+	const target = needle.toLowerCase();
+	let from = 0;
+	while (from <= lower.length - target.length) {
+		const at = lower.indexOf(target, from);
+		if (at < 0) return -1;
+		const before = at > 0 ? lower[at - 1] : "";
+		const after = lower[at + target.length] ?? "";
+		const boundedBefore = before === "" || !WORD.test(before) || !WORD.test(target[0]);
+		const boundedAfter = after === "" || !WORD.test(after) || !WORD.test(target[target.length - 1]);
+		if (boundedBefore && boundedAfter) return at;
+		from = at + 1;
+	}
+	return -1;
+}
+
+/**
+ * Earliest option label mentioned in `text`; a longer label wins a tie at the
+ * same position (so `xhigh` beats `high` where both start together).
+ */
+export function parseChoiceReply<L extends string>(text: string, labels: readonly L[]): L | undefined {
+	let best: L | undefined;
+	let bestAt = Number.POSITIVE_INFINITY;
+	for (const label of labels) {
+		const at = indexOfWord(text, label);
+		if (at < 0) continue;
+		if (at < bestAt || (at === bestAt && best !== undefined && label.length > best.length)) {
+			best = label;
+			bestAt = at;
+		}
+	}
+	return best;
+}
+
+/** `true` when a yes-word precedes any no-word, `false` for the reverse, `undefined` when neither appears. */
+export function parseNoulReply(text: string): boolean | undefined {
+	const yes = [indexOfWord(text, "yes"), indexOfWord(text, "true")].filter(at => at >= 0);
+	const no = [indexOfWord(text, "no"), indexOfWord(text, "false")].filter(at => at >= 0);
+	const yesAt = yes.length > 0 ? Math.min(...yes) : -1;
+	const noAt = no.length > 0 ? Math.min(...no) : -1;
+	if (yesAt < 0 && noAt < 0) return undefined;
+	if (noAt < 0) return true;
+	if (yesAt < 0) return false;
+	return yesAt < noAt;
+}
+
+/** Standalone integers: not glued to a word (`v2`) and not one side of a decimal (`1.5`); a trailing period is fine. */
+const INTEGER = /(?<![\p{L}\p{N}_])(?<!\d\.)(\d+)(?![\p{L}\p{N}_])(?!\.\d)/gu;
+
+/** First standalone integer in `[0, levels)`, or `undefined`. */
+export function parseScoreReply(text: string, levels: number): number | undefined {
+	for (const match of text.matchAll(INTEGER)) {
+		const value = Number(match[1]);
+		if (value < levels) return value;
+	}
+	return undefined;
+}
+
+/**
+ * Split a multi-question reply into `id → answer text`. Lines are matched as
+ * `<id>: <answer>` (also `=` / `-` separators and quoted ids); unknown ids are
+ * ignored so a chatty preamble does not poison parsing.
+ */
+export function splitAnswerLines(text: string, ids: readonly string[]): Map<string, string> {
+	const byId = new Map<string, string>();
+	const wanted = new Set(ids);
+	for (const rawLine of text.split("\n")) {
+		const line = rawLine.replace(/^[\s\-*•]+/, "").trim();
+		const separator = line.search(/\s*[:=]\s*|\s+-\s+/);
+		if (separator <= 0) continue;
+		const id = line.slice(0, separator).replace(/^[`"']|[`"']$/g, "");
+		if (!wanted.has(id) || byId.has(id)) continue;
+		byId.set(id, line.slice(separator).replace(/^\s*[:=-]\s*/, ""));
+	}
+	return byId;
+}
+
+function oneHot<L extends string>(labels: readonly L[], chosen: L): Record<L, number> {
+	const probabilities = {} as Record<L, number>;
+	for (const label of labels) probabilities[label] = label === chosen ? 1 : 0;
+	return probabilities;
+}
+
+/** Parse one question's keyword reply into its typed, one-hot answer. */
+export function parseAnswer(id: string, question: Question, reply: string): Answer {
+	switch (question.type) {
+		case "choice": {
+			const labels = Object.keys(question.criteria);
+			const choice = parseChoiceReply(reply, labels);
+			if (choice === undefined) throw new JudgmentParseError(id, reply, "no option label in reply");
+			return { type: "choice", choice, probabilities: oneHot(labels, choice), confidence: 1 };
+		}
+		case "noul": {
+			const verdict = parseNoulReply(reply);
+			if (verdict === undefined) throw new JudgmentParseError(id, reply, "no yes/no in reply");
+			return { type: "noul", noul: verdict ? 1 : 0 };
+		}
+		case "score": {
+			const level = parseScoreReply(reply, question.criteria.length);
+			if (level === undefined) throw new JudgmentParseError(id, reply, "no level number in reply");
+			const probabilities: Record<string, number> = {};
+			for (let index = 0; index < question.criteria.length; index++) {
+				probabilities[String(index)] = index === level ? 1 : 0;
+			}
+			return { type: "score", score: level, probabilities, confidence: 1 };
+		}
+	}
+}
+
+export class TextJudge implements Judge {
+	readonly label: string;
+	readonly #backend: TextBackend;
+
+	constructor(backend: TextBackend) {
+		this.#backend = backend;
+		this.label = `${backend.provider}/${backend.model}`;
+	}
+
+	async judge<Q extends Questions>(
+		request: JudgmentRequest<Q>,
+		options: JudgeOptions = {},
+	): Promise<JudgmentResult<Q>> {
+		const ids = Object.keys(request.questions);
+		if (ids.length === 0) throw new Error("judgment request has no questions");
+		const rendered = renderJudgmentPrompt(request, { guardState: this.#backend.guardState });
+		const retries = this.#backend.parseRetries ?? 0;
+		for (let attempt = 0; ; attempt++) {
+			const textPrompt =
+				attempt === 0
+					? rendered
+					: {
+							system: prompt.render(textJudgeRetryTemplate, {
+								system: rendered.system,
+								multi: ids.length > 1,
+							}),
+							user: rendered.user,
+							retry: true,
+						};
+			const completion = await this.#backend.complete(textPrompt, options);
+			try {
+				const replies =
+					ids.length === 1 ? new Map([[ids[0], completion.text]]) : splitAnswerLines(completion.text, ids);
+				const answers: Record<string, Answer> = {};
+				for (const id of ids) {
+					const reply = replies.get(id);
+					if (reply === undefined) {
+						throw new JudgmentParseError(id, completion.text, "no answer line for question");
+					}
+					answers[id] = parseAnswer(id, request.questions[id], reply);
+				}
+				return {
+					api: this.#backend.api,
+					provider: this.#backend.provider,
+					model: this.#backend.model,
+					answers: answers as JudgmentResult<Q>["answers"],
+					usage: completion.usage ?? tokenUsage(0, 0),
+				};
+			} catch (error) {
+				if (!(error instanceof JudgmentParseError) || attempt >= retries) throw error;
+			}
+		}
+	}
+}

package/src/judgment/types.ts

@@ -0,0 +1,128 @@
+/**
+ * Typed judgments: small, structured decisions over a JSON state.
+ *
+ * A {@link Judge} answers a map of named questions — {@link ChoiceQuestion}
+ * (one option from a fixed set), {@link NoulQuestion} (probability that a
+ * yes/no condition holds), {@link ScoreQuestion} (position on ordered levels)
+ * — about one {@link JudgmentState}. Every question in a request sees the same
+ * state and is answered independently, so callers batch independent questions
+ * into one call. The shape mirrors TypeSafe's System One API so the native
+ * backend ({@link TypeSafeJudge}) forwards requests verbatim, while the text
+ * bridge ({@link TextJudge}) renders the same questions into keyword prompts
+ * for an ordinary chat model.
+ */
+import type { Usage } from "../types";
+
+/** JSON-compatible value; readonly containers are accepted so `as const` state passes through. */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | { readonly [key: string]: JsonValue };
+
+/** The content a request evaluates: plain text, or a named-field object / array for multi-part context. */
+export type JudgmentState = string | { readonly [key: string]: JsonValue } | readonly JsonValue[];
+
+/** Pick one option from a fixed set. `criteria` maps option → rubric (`null` when the name suffices). */
+export interface ChoiceQuestion<L extends string = string> {
+	type: "choice";
+	instructions: string;
+	criteria: Record<L, string | null>;
+}
+
+/** Probability that a yes/no condition holds. `criteria` optionally spells out what yes and no mean. */
+export interface NoulQuestion {
+	type: "noul";
+	instructions: string;
+	criteria?: { true?: string; false?: string };
+}
+
+/** Position on ordered levels; `criteria` lists at least two level descriptions from lowest to highest. */
+export interface ScoreQuestion {
+	type: "score";
+	instructions: string;
+	criteria: readonly [string, string, ...string[]];
+}
+
+export type Question = ChoiceQuestion | NoulQuestion | ScoreQuestion;
+
+/** Questions keyed by caller-chosen ids; answers come back under the same ids. */
+export type Questions = Record<string, Question>;
+
+export interface ChoiceAnswer<L extends string = string> {
+	type: "choice";
+	/** Highest-probability option. */
+	choice: L;
+	/** Every option mapped to its probability (sums to 1). */
+	probabilities: Record<L, number>;
+	/** Concentration of the distribution, 0–1. */
+	confidence: number;
+}
+
+export interface NoulAnswer {
+	type: "noul";
+	/** Probability of yes, 0–1. */
+	noul: number;
+}
+
+export interface ScoreAnswer {
+	type: "score";
+	/** Probability-weighted level index; may land between levels. */
+	score: number;
+	/** Level index (as a string key) mapped to its probability. */
+	probabilities: Record<string, number>;
+	/** Concentration of the distribution, 0–1. */
+	confidence: number;
+}
+
+export type Answer = ChoiceAnswer | NoulAnswer | ScoreAnswer;
+
+/** The answer type for a question, preserving choice labels. */
+export type AnswerFor<Q extends Question> =
+	Q extends ChoiceQuestion<infer L> ? ChoiceAnswer<L> : Q extends NoulQuestion ? NoulAnswer : ScoreAnswer;
+
+export interface JudgmentRequest<Q extends Questions = Questions> {
+	state: JudgmentState;
+	questions: Q;
+}
+
+export interface JudgmentResult<Q extends Questions = Questions> {
+	/** Transport that produced the answers (`typesafe`, or the chat model's api). */
+	api: string;
+	provider: string;
+	model: string;
+	answers: { [K in keyof Q]: AnswerFor<Q[K]> };
+	usage: Usage;
+}
+
+export interface JudgeOptions {
+	signal?: AbortSignal;
+}
+
+/** Answers typed questions about a state. Implementations are stateless and safe to share. */
+export interface Judge {
+	/** Backend description for logs, e.g. `typesafe/jev-latest`. */
+	readonly label: string;
+	judge<Q extends Questions>(request: JudgmentRequest<Q>, options?: JudgeOptions): Promise<JudgmentResult<Q>>;
+}
+
+/** Thrown when a backend returned output that does not resolve to an answer for every question. */
+export class JudgmentParseError extends Error {
+	readonly questionId: string;
+	readonly output: string;
+
+	constructor(questionId: string, output: string, detail: string) {
+		super(`judgment "${questionId}": ${detail}: ${JSON.stringify(output)}`);
+		this.name = "JudgmentParseError";
+		this.questionId = questionId;
+		this.output = output;
+	}
+}
+
+/** Zero-cost usage for a request whose backend reports only token counts. */
+export function tokenUsage(input: number, output: number): Usage {
+	return {
+		input,
+		output,
+		cacheRead: 0,
+		cacheWrite: 0,
+		totalTokens: input + output,
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+	};
+}

package/src/judgment/typesafe.ts

@@ -0,0 +1,173 @@
+/**
+ * TypeSafe System One client: the native {@link Judge} backend.
+ *
+ * Forwards a {@link JudgmentRequest} verbatim to `POST /v1/systemone` and maps
+ * the typed answers back. Credentials flow through {@link withAuth}, so a
+ * stored key rotates on 401/403 exactly like chat providers; transient
+ * 429/5xx responses retry with bounded, `retry-after`-aware backoff.
+ *
+ * Environment (mirrors the official SDK): `TYPESAFE_API_KEY` is resolved by
+ * the auth registry (`rules/auth/typesafe.kdl`), `TYPESAFE_BASE_URL`
+ * overrides the API root, `TYPESAFE_DEFAULT_MODEL` the model.
+ */
+import type { FetchImpl } from "@oh-my-pi/pi-catalog/types";
+import { $env } from "@oh-my-pi/pi-utils";
+import { type ApiKey, withAuth } from "../auth-retry";
+import * as AIError from "../error";
+import { getRetryAfterMsFromHeaders } from "../utils/retry-after";
+import {
+	type Answer,
+	type Judge,
+	type JudgeOptions,
+	type JudgmentRequest,
+	type JudgmentResult,
+	type Questions,
+	tokenUsage,
+} from "./types";
+
+export const TYPESAFE_PROVIDER = "typesafe";
+export const TYPESAFE_DEFAULT_BASE_URL = "https://api.typesafe.ai";
+export const TYPESAFE_DEFAULT_MODEL = "jev-latest";
+
+/** `TYPESAFE_BASE_URL` when set, else the public API root; trailing slashes stripped. */
+export function typesafeBaseUrl(): string {
+	return ($env.TYPESAFE_BASE_URL?.trim() || TYPESAFE_DEFAULT_BASE_URL).replace(/\/+$/, "");
+}
+
+/** `TYPESAFE_DEFAULT_MODEL` when set, else {@link TYPESAFE_DEFAULT_MODEL}. */
+export function typesafeModel(): string {
+	return $env.TYPESAFE_DEFAULT_MODEL?.trim() || TYPESAFE_DEFAULT_MODEL;
+}
+
+export interface TypeSafeJudgeOptions {
+	apiKey: ApiKey;
+	/** Defaults to {@link typesafeBaseUrl}. */
+	baseUrl?: string;
+	/** Defaults to {@link typesafeModel}. */
+	model?: string;
+	fetch?: FetchImpl;
+	/** Per-attempt timeout; defaults to {@link DEFAULT_TIMEOUT_MS}. */
+	timeoutMs?: number;
+}
+
+/** Non-2xx response from the TypeSafe API. */
+export class TypeSafeApiError extends AIError.ProviderHttpError {
+	override readonly name = "TypeSafeApiError";
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_ATTEMPTS = 3;
+const BACKOFF_BASE_MS = 500;
+const BACKOFF_MAX_MS = 5_000;
+
+/** Wire shape of `GET /v1/models`. */
+export interface TypeSafeModelCard {
+	name: string;
+	description: string;
+	release_date: string;
+}
+
+interface SystemOneResponse {
+	model: string;
+	answers: Record<string, Answer>;
+	usage: { input_tokens: number; output_tokens: number };
+}
+
+/** Server hint wins (capped); otherwise exponential backoff from {@link BACKOFF_BASE_MS}. */
+function backoffMs(attempt: number, headers: Headers | undefined): number {
+	const hinted = headers === undefined ? undefined : getRetryAfterMsFromHeaders(headers);
+	if (hinted !== undefined) return Math.min(hinted, BACKOFF_MAX_MS);
+	return Math.min(BACKOFF_BASE_MS * 2 ** attempt, BACKOFF_MAX_MS);
+}
+
+export class TypeSafeJudge implements Judge {
+	readonly label: string;
+	readonly model: string;
+	readonly baseUrl: string;
+	readonly #apiKey: ApiKey;
+	readonly #fetch: FetchImpl;
+	readonly #timeoutMs: number;
+
+	constructor(options: TypeSafeJudgeOptions) {
+		this.#apiKey = options.apiKey;
+		this.baseUrl = (options.baseUrl ?? typesafeBaseUrl()).replace(/\/+$/, "");
+		this.model = options.model ?? typesafeModel();
+		this.#fetch = options.fetch ?? fetch;
+		this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		this.label = `${TYPESAFE_PROVIDER}/${this.model}`;
+	}
+
+	async judge<Q extends Questions>(request: JudgmentRequest<Q>, options?: JudgeOptions): Promise<JudgmentResult<Q>> {
+		const body = JSON.stringify({ state: request.state, model: this.model, questions: request.questions });
+		const response = await this.#request<SystemOneResponse>("POST", "/v1/systemone", body, options?.signal);
+		for (const id in request.questions) {
+			const answer = response.answers[id];
+			if (answer === undefined || answer.type !== request.questions[id].type) {
+				throw new AIError.ProviderResponseError(
+					`TypeSafe response is missing a "${request.questions[id].type}" answer for question "${id}"`,
+					{ provider: TYPESAFE_PROVIDER, kind: "envelope" },
+				);
+			}
+		}
+		return {
+			api: TYPESAFE_PROVIDER,
+			provider: TYPESAFE_PROVIDER,
+			model: response.model,
+			answers: response.answers as JudgmentResult<Q>["answers"],
+			usage: tokenUsage(response.usage.input_tokens, response.usage.output_tokens),
+		};
+	}
+
+	/** Models available to the account (`GET /v1/models`); also the login validation probe. */
+	async listModels(signal?: AbortSignal): Promise<TypeSafeModelCard[]> {
+		const response = await this.#request<{ models: TypeSafeModelCard[] }>("GET", "/v1/models", undefined, signal);
+		if (!Array.isArray(response.models)) {
+			throw new AIError.ProviderResponseError("TypeSafe /v1/models response is missing `models`", {
+				provider: TYPESAFE_PROVIDER,
+				kind: "envelope",
+			});
+		}
+		return response.models;
+	}
+
+	async #request<T>(method: "GET" | "POST", path: string, body: string | undefined, signal?: AbortSignal): Promise<T> {
+		return withAuth(this.#apiKey, key => this.#attempt<T>(method, path, body, key, signal), { signal });
+	}
+
+	async #attempt<T>(
+		method: "GET" | "POST",
+		path: string,
+		body: string | undefined,
+		key: string,
+		signal: AbortSignal | undefined,
+	): Promise<T> {
+		const url = `${this.baseUrl}${path}`;
+		const headers: Record<string, string> = { Authorization: `Bearer ${key}`, Accept: "application/json" };
+		if (body !== undefined) headers["Content-Type"] = "application/json";
+		for (let attempt = 0; ; attempt++) {
+			signal?.throwIfAborted();
+			const timeout = AbortSignal.timeout(this.#timeoutMs);
+			let response: Response;
+			try {
+				response = await this.#fetch(url, {
+					method,
+					headers,
+					body,
+					signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+				});
+			} catch (error) {
+				if (signal?.aborted || attempt + 1 >= MAX_ATTEMPTS) throw error;
+				await Bun.sleep(backoffMs(attempt, undefined));
+				continue;
+			}
+			if (response.ok) return (await response.json()) as T;
+			const text = await response.text();
+			const error = new TypeSafeApiError(`TypeSafe API error (${response.status}): ${text}`, response.status, {
+				headers: response.headers,
+			});
+			const transient = response.status === 408 || response.status === 429 || response.status >= 500;
+			if (!transient || attempt + 1 >= MAX_ATTEMPTS) throw error;
+			await Bun.sleep(backoffMs(attempt, response.headers));
+		}
+	}
+}

package/src/registry/oauth/github-copilot.ts

@@ -29,7 +29,7 @@ import {
 } from "../../providers/github-copilot-headers";
 import * as AIError from "../../error";
 import type { FetchImpl } from "../../types";
-import type { OAuthController, OAuthCredentials } from "./types";
+import type { OAuthController, OAuthCredentials, OAuthPrompt } from "./types";
 
 const OPENCODE_CLIENT_ID = "Ov23li8tweQw6odWQebz";
 const COPILOT_CLI_CLIENT_ID = "Ov23ctDVkRmgkPke0Mmm";
@@ -55,7 +55,7 @@ const SLOW_DOWN_POLL_INTERVAL_MULTIPLIER = 1.4;
 
 type GitHubCopilotLoginOptions = {
 	onAuth: (url: string, instructions?: string) => void;
-	onPrompt: (prompt: { message: string; placeholder?: string; allowEmpty?: boolean }) => Promise<string>;
+	onPrompt: (prompt: OAuthPrompt) => Promise<string>;
 	onProgress?: (message: string) => void;
 	copilotIntegrationId?: unknown;
 	signal?: AbortSignal;

package/src/registry/oauth/kimi.ts

@@ -6,7 +6,7 @@ import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { getAgentDir } from "@oh-my-pi/pi-utils";
+import { getAgentDir, once } from "@oh-my-pi/pi-utils";
 import packageJson from "../../../package.json" with { type: "json" };
 
 const DEVICE_ID_FILENAME = "kimi-device-id";
@@ -57,7 +57,8 @@ function sanitizeHeaderValue(value: string, fallback = ""): string {
 	return sanitized || fallback;
 }
 
-export let getKimiCommonHeaders = () => {
+/** Lazily resolve the process-stable device headers used by Kimi requests. */
+export const getKimiCommonHeaders = once(() => {
 	const headers = Object.freeze({
 		"User-Agent": `KimiCLI/${packageJson.version}`,
 		"X-Msh-Platform": "kimi_cli",
@@ -67,6 +68,5 @@ export let getKimiCommonHeaders = () => {
 		"X-Msh-Os-Version": sanitizeHeaderValue(os.version(), "unknown"),
 		"X-Msh-Device-Id": sanitizeHeaderValue(getDeviceId(), "unknown"),
 	});
-	getKimiCommonHeaders = () => headers;
 	return headers;
-};
+});

package/src/registry/oauth/types.ts

@@ -37,6 +37,8 @@ export type OAuthPrompt = {
 	message: string;
 	placeholder?: string;
 	allowEmpty?: boolean;
+	/** Request masked entry from interactive hosts. Hosts that cannot hide input must reject the prompt. */
+	secret?: boolean;
 };
 
 export type OAuthAuthInfo = {