@oh-my-pi/pi-ai 18.9.1 → 18.9.2

package/src/judgment/native.ts

@@ -0,0 +1,333 @@
+/**
+ * Native judgment client: the {@link Judge} backend for catalog models whose
+ * API answers typed questions directly ({@link isJudgmentApi}).
+ *
+ * Each judgment API is one wire dialect: TypeSafe's System One route
+ * (`POST /v1/systemone`), OpenRouter Decisions (`POST /api/alpha/decisions`,
+ * same body), Cloudflare Workers AI decision models (`POST /ai/run/{model}`,
+ * same body in Cloudflare's envelope; `systemone.ts`), and OpenAI Decisions
+ * (`POST /v1/decisions`, translated both ways; `openai-decisions.ts`).
+ * 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. Endpoints that cap the questions per
+ * request (the catalog's `judgment-questions-max`, e.g. OpenJEV at 16) get
+ * oversized requests split into chunks under `maxQuestions`, at most
+ * {@link CHUNK_PARALLEL} in flight at once.
+ *
+ * Environment (mirrors the official TypeSafe SDK, for judges built without an
+ * explicit model): `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 { resolveJudgmentQuestionsMax } from "@oh-my-pi/pi-catalog/compat/judgment-questions";
+import { TYPESAFE_DEFAULT_BASE_URL } from "@oh-my-pi/pi-catalog/discovery";
+import type { Api, FetchImpl } from "@oh-my-pi/pi-catalog/types";
+import { $env, isRecord } from "@oh-my-pi/pi-utils";
+import { type ApiKey, withAuth } from "../auth-retry";
+import * as AIError from "../error";
+import type { Model, Usage } from "../types";
+import { getRetryAfterMsFromHeaders } from "../utils/retry-after";
+import { openaiDecisionsWire } from "./openai-decisions";
+import { openrouterDecisionsWire, typesafeWire, workersAiWire } from "./systemone";
+import {
+	type Answer,
+	type Judge,
+	type JudgeOptions,
+	type JudgmentRequest,
+	type JudgmentResult,
+	type Questions,
+	tokenUsage,
+} from "./types";
+import type { JudgmentWire } from "./wire";
+
+export const TYPESAFE_PROVIDER = "typesafe";
+export const TYPESAFE_DEFAULT_MODEL = "jev-latest";
+
+const JUDGMENT_WIRES = {
+	typesafe: typesafeWire,
+	"openrouter-decisions": openrouterDecisionsWire,
+	"workers-ai-systemone": workersAiWire,
+	"openai-decisions": openaiDecisionsWire,
+} as const satisfies Partial<Record<Api, JudgmentWire>>;
+
+/** APIs {@link NativeJudge} can serve. */
+export type JudgmentApi = keyof typeof JUDGMENT_WIRES;
+
+/** Whether a catalog API answers judgments natively. */
+export function isJudgmentApi(api: Api): api is JudgmentApi {
+	return Object.hasOwn(JUDGMENT_WIRES, api);
+}
+
+/** `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;
+}
+
+/** Credential and transport overrides for a judge; see {@link createNativeJudge}. */
+export interface NativeJudgeConnection {
+	apiKey: ApiKey;
+	/** Static headers attached to judgment requests (e.g. proxy routing, gateway auth). */
+	headers?: Record<string, string>;
+	fetch?: FetchImpl;
+}
+
+export interface NativeJudgeOptions extends NativeJudgeConnection {
+	/** Wire dialect; defaults to TypeSafe's own API. */
+	api?: JudgmentApi;
+	/** Catalog provider reported on results; defaults to {@link TYPESAFE_PROVIDER}. */
+	provider?: string;
+	/** Defaults to {@link typesafeBaseUrl}. */
+	baseUrl?: string;
+	/** Wire model id; defaults to {@link typesafeModel}. */
+	model?: string;
+	/** Per-attempt timeout; defaults to {@link DEFAULT_TIMEOUT_MS}. */
+	timeoutMs?: number;
+	/**
+	 * Most questions per request the endpoint accepts, a positive integer; larger
+	 * requests are split. Unset: no cap.
+	 */
+	maxQuestions?: number;
+}
+
+/** Per-call options for {@link NativeJudge.judge}. */
+export interface NativeJudgeCallOptions extends JudgeOptions {
+	/**
+	 * Called before a split judgment rejects, with the summed usage of the chunks that had already
+	 * succeeded: billed upstream, but their answers are discarded with the failure. Not called when
+	 * no chunk succeeded or the request was not split.
+	 */
+	onPartialUsage?: (usage: Usage) => void;
+}
+
+/** Non-2xx response from a native judgment API. */
+export class JudgmentApiError extends AIError.ProviderHttpError {
+	override readonly name = "JudgmentApiError";
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_ATTEMPTS = 3;
+const BACKOFF_BASE_MS = 500;
+const BACKOFF_MAX_MS = 5_000;
+/** Chunks of one split judgment in flight at once, so a split never bursts the endpoint unboundedly. */
+const CHUNK_PARALLEL = 4;
+
+/** 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);
+}
+
+/** Whether `value` is a wire answer of `type`. Answers are trusted past their discriminant, as forwarded verbatim. */
+function isAnswerOf(value: unknown, type: Answer["type"]): value is Answer {
+	return isRecord(value) && value.type === type;
+}
+
+export class NativeJudge implements Judge {
+	readonly label: string;
+	readonly api: JudgmentApi;
+	readonly provider: string;
+	/** Wire model id sent with every request. */
+	readonly model: string;
+	readonly baseUrl: string;
+	readonly #wire: JudgmentWire;
+	readonly #apiKey: ApiKey;
+	readonly #headers: Record<string, string> | undefined;
+	readonly #fetch: FetchImpl;
+	readonly #timeoutMs: number;
+	readonly #maxQuestions: number | undefined;
+
+	constructor(options: NativeJudgeOptions) {
+		this.#apiKey = options.apiKey;
+		this.api = options.api ?? TYPESAFE_PROVIDER;
+		this.#wire = JUDGMENT_WIRES[this.api];
+		this.provider = options.provider ?? TYPESAFE_PROVIDER;
+		this.baseUrl = (options.baseUrl ?? typesafeBaseUrl()).replace(/\/+$/, "");
+		this.model = options.model ?? typesafeModel();
+		this.#headers = options.headers;
+		this.#fetch = options.fetch ?? fetch;
+		this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		if (options.maxQuestions !== undefined && !(Number.isInteger(options.maxQuestions) && options.maxQuestions > 0)) {
+			throw new RangeError(`NativeJudge maxQuestions must be a positive integer, got ${options.maxQuestions}`);
+		}
+		this.#maxQuestions = options.maxQuestions;
+		this.label = `${this.provider}/${this.model}`;
+	}
+
+	async judge<Q extends Questions>(
+		request: JudgmentRequest<Q>,
+		options?: NativeJudgeCallOptions,
+	): Promise<JudgmentResult<Q>> {
+		const ids = Object.keys(request.questions);
+		const cap = this.#maxQuestions;
+		if (cap !== undefined && ids.length > cap) return this.#judgeChunked(request, ids, cap, options);
+		return this.#judgeOnce(request, options);
+	}
+
+	/**
+	 * Answer `request` in requests of at most `cap` questions each, {@link CHUNK_PARALLEL} at a time;
+	 * answers merge and usage sums. The first failing chunk aborts its in-flight siblings and stops
+	 * dispatch, so a doomed judgment stops spending; once every chunk settles, the usage of those that
+	 * succeeded goes to `onPartialUsage` before the judgment rejects.
+	 */
+	async #judgeChunked<Q extends Questions>(
+		request: JudgmentRequest<Q>,
+		ids: string[],
+		cap: number,
+		options: NativeJudgeCallOptions | undefined,
+	): Promise<JudgmentResult<Q>> {
+		const chunks: Questions[] = [];
+		for (let start = 0; start < ids.length; start += cap) {
+			const questions: Questions = {};
+			for (const id of ids.slice(start, start + cap)) questions[id] = request.questions[id];
+			chunks.push(questions);
+		}
+		const failed = new AbortController();
+		const signal = options?.signal ? AbortSignal.any([options.signal, failed.signal]) : failed.signal;
+		const chunkOptions = { signal };
+		const results: JudgmentResult[] = [];
+		let next = 0;
+		const drain = async (): Promise<void> => {
+			while (next < chunks.length && !signal.aborted) {
+				const index = next++;
+				try {
+					results[index] = await this.#judgeOnce({ state: request.state, questions: chunks[index] }, chunkOptions);
+				} catch (error) {
+					failed.abort(error);
+					throw error;
+				}
+			}
+		};
+		// Settle every worker, not just the first failure, so no sibling's billed result goes uncounted.
+		await Promise.allSettled(Array.from({ length: Math.min(CHUNK_PARALLEL, chunks.length) }, drain));
+		const answers: Record<string, Answer> = {};
+		let settled = 0;
+		let input = 0;
+		let output = 0;
+		let cost = 0;
+		for (const result of results) {
+			if (result === undefined) continue;
+			settled++;
+			Object.assign(answers, result.answers);
+			input += result.usage.input;
+			output += result.usage.output;
+			cost += result.usage.cost.total;
+		}
+		// Every chunk failure aborts `failed`, so `signal` carries the first failure or the caller's abort.
+		if (signal.aborted) {
+			if (settled > 0) options?.onPartialUsage?.(tokenUsage(input, output, cost));
+			throw signal.reason;
+		}
+		return {
+			api: this.api,
+			provider: this.provider,
+			model: results[0].model,
+			answers: answers as JudgmentResult<Q>["answers"],
+			usage: tokenUsage(input, output, cost),
+		};
+	}
+
+	async #judgeOnce<Q extends Questions>(
+		request: JudgmentRequest<Q>,
+		options: JudgeOptions | undefined,
+	): Promise<JudgmentResult<Q>> {
+		const body = JSON.stringify(this.#wire.encode(request, this.model));
+		const signal = options?.signal;
+		const payload = await withAuth(this.#apiKey, key => this.#attempt(body, key, signal), { signal });
+		const decoded = this.#wire.decode(payload);
+		if (!decoded) {
+			throw new AIError.ProviderResponseError(`${this.label} returned a malformed judgment response`, {
+				provider: this.provider,
+				kind: "envelope",
+			});
+		}
+		const answers: Record<string, Answer> = {};
+		for (const id in request.questions) {
+			const type = request.questions[id].type;
+			if (decoded.refused.includes(id)) {
+				throw new AIError.ProviderResponseError(`${this.label} refused to answer question "${id}"`, {
+					provider: this.provider,
+					kind: "content-blocked",
+				});
+			}
+			const answer = decoded.answers[id];
+			if (!isAnswerOf(answer, type)) {
+				throw new AIError.ProviderResponseError(
+					`${this.label} response is missing a "${type}" answer for question "${id}"`,
+					{ provider: this.provider, kind: "envelope" },
+				);
+			}
+			answers[id] = answer;
+		}
+		return {
+			api: this.api,
+			provider: this.provider,
+			model: decoded.model ?? this.model,
+			// Each id was checked against its question's type above.
+			answers: answers as JudgmentResult<Q>["answers"],
+			usage: decoded.usage,
+		};
+	}
+
+	async #attempt(body: string, key: string, signal: AbortSignal | undefined): Promise<unknown> {
+		const target = this.#wire.target(this.baseUrl, this.model, key);
+		const headers: Record<string, string> = {
+			...this.#headers,
+			Authorization: `Bearer ${target.token}`,
+			Accept: "application/json",
+			"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(target.url, {
+					method: "POST",
+					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();
+			const text = await response.text();
+			const error = new JudgmentApiError(`${this.label} 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));
+		}
+	}
+}
+
+/**
+ * The {@link NativeJudge} for a catalog judge model: its API's dialect, wire id
+ * (`requestModelId ?? id`), base URL, and catalog question cap
+ * (`judgment-questions-max`). Shared by the coding agent's judge chain and the
+ * auth-gateway System One route so both address a model the same way.
+ *
+ * @throws ConfigurationError when the model's API is not a judgment API.
+ */
+export function createNativeJudge(model: Model, connection: NativeJudgeConnection): NativeJudge {
+	if (!isJudgmentApi(model.api)) {
+		throw new AIError.ConfigurationError(`${model.provider}/${model.id} does not answer native judgments`);
+	}
+	return new NativeJudge({
+		...connection,
+		api: model.api,
+		provider: model.provider,
+		model: model.requestModelId ?? model.id,
+		baseUrl: model.baseUrl,
+		maxQuestions: resolveJudgmentQuestionsMax(model),
+	});
+}

package/src/judgment/openai-decisions-predicate.md

@@ -0,0 +1,9 @@
+{{{instructions}}}
+{{#if yes}}
+
+True means: {{{yes}}}
+{{/if}}
+{{#if no}}
+
+False means: {{{no}}}
+{{/if}}

package/src/judgment/openai-decisions.ts

@@ -0,0 +1,129 @@
+/**
+ * OpenAI Decisions dialect (`POST {baseUrl}/decisions`, `gpt-6-luna`).
+ *
+ * The API asks the same three question kinds as System One under other
+ * names, as an ordered list instead of an id map, so requests and answers are
+ * translated both ways:
+ *
+ * | System One                                  | Decisions                                     |
+ * | ------------------------------------------- | --------------------------------------------- |
+ * | `state` (text or JSON)                      | `input` (text; JSON state is serialized)      |
+ * | question id                                 | `name`, echoed on its answer                  |
+ * | `noul` + optional yes/no `criteria`         | `predicate`; criteria fold into instructions  |
+ * | `choice` `criteria` option → rubric         | `choices: [{ value, description? }]`          |
+ * | `score` `criteria` level descriptions       | `levels: [{ label }]`, lowest first           |
+ * | `noul` answer `noul`                        | `predicate` answer `probability`              |
+ * | `probabilities` map by option / level index | `probabilities: [{ value, probability }]`     |
+ *
+ * A `refusal` answer marks a question the model declined. Billing is input
+ * tokens only, so cost is priced from the catalog model.
+ */
+import { isRecord, prompt } from "@oh-my-pi/pi-utils";
+import predicateTemplate from "./openai-decisions-predicate.md" with { type: "text" };
+import { type Answer, type Question, tokenUsage } from "./types";
+import { finiteNumber, type JudgmentWire } from "./wire";
+
+type DecisionQuestion =
+	| { type: "predicate"; name: string; instructions: string }
+	| { type: "choice"; name: string; instructions: string; choices: { value: string; description?: string }[] }
+	| { type: "score"; name: string; instructions: string; levels: { label: string }[] };
+
+function encodeQuestion(name: string, question: Question): DecisionQuestion {
+	switch (question.type) {
+		case "noul":
+			return {
+				type: "predicate",
+				name,
+				instructions: question.criteria
+					? prompt.render(predicateTemplate, {
+							instructions: question.instructions,
+							yes: question.criteria.true,
+							no: question.criteria.false,
+						})
+					: question.instructions,
+			};
+		case "choice":
+			return {
+				type: "choice",
+				name,
+				instructions: question.instructions,
+				choices: Object.entries(question.criteria).map(([value, description]) =>
+					description === null ? { value } : { value, description },
+				),
+			};
+		case "score":
+			return {
+				type: "score",
+				name,
+				instructions: question.instructions,
+				levels: question.criteria.map(label => ({ label })),
+			};
+	}
+}
+
+/** `[{ value, probability }]` as a probability map keyed by the stringified value; `undefined` when malformed. */
+function probabilityMap(value: unknown): Record<string, number> | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const map: Record<string, number> = {};
+	for (const entry of value) {
+		if (!isRecord(entry) || typeof entry.probability !== "number") return undefined;
+		if (typeof entry.value !== "string" && typeof entry.value !== "boolean" && typeof entry.value !== "number") {
+			return undefined;
+		}
+		map[String(entry.value)] = entry.probability;
+	}
+	return map;
+}
+
+/** The System One answer for one Decisions answer; `undefined` for refusals and malformed entries. */
+function decodeAnswer(entry: Record<string, unknown>): Answer | undefined {
+	switch (entry.type) {
+		case "predicate":
+			return typeof entry.probability === "number" ? { type: "noul", noul: entry.probability } : undefined;
+		case "choice": {
+			const probabilities = probabilityMap(entry.probabilities);
+			if (!probabilities || typeof entry.confidence !== "number") return undefined;
+			if (typeof entry.choice !== "string" && typeof entry.choice !== "boolean") return undefined;
+			return { type: "choice", choice: String(entry.choice), probabilities, confidence: entry.confidence };
+		}
+		case "score": {
+			const probabilities = probabilityMap(entry.probabilities);
+			if (!probabilities || typeof entry.score !== "number" || typeof entry.confidence !== "number")
+				return undefined;
+			return { type: "score", score: entry.score, probabilities, confidence: entry.confidence };
+		}
+		default:
+			return undefined;
+	}
+}
+
+/** OpenAI's `/v1/decisions` route. */
+export const openaiDecisionsWire: JudgmentWire = {
+	target: (baseUrl, _model, key) => ({ url: `${baseUrl}/decisions`, token: key }),
+	encode: (request, model) => ({
+		model,
+		input: typeof request.state === "string" ? request.state : JSON.stringify(request.state),
+		questions: Object.entries(request.questions).map(([name, question]) => encodeQuestion(name, question)),
+	}),
+	decode(payload) {
+		if (!isRecord(payload) || !Array.isArray(payload.answers)) return undefined;
+		const answers: Record<string, Answer> = {};
+		const refused: string[] = [];
+		for (const entry of payload.answers) {
+			if (!isRecord(entry) || typeof entry.name !== "string") continue;
+			if (entry.type === "refusal") {
+				refused.push(entry.name);
+				continue;
+			}
+			const answer = decodeAnswer(entry);
+			if (answer) answers[entry.name] = answer;
+		}
+		const usage = isRecord(payload.usage) ? payload.usage : {};
+		return {
+			model: typeof payload.model === "string" ? payload.model : undefined,
+			answers,
+			refused,
+			usage: tokenUsage(finiteNumber(usage.input_tokens), finiteNumber(usage.output_tokens)),
+		};
+	},
+};

package/src/judgment/systemone.ts

@@ -0,0 +1,65 @@
+/**
+ * TypeSafe System One dialects. The request body (`{ model, state, questions }`)
+ * and answer map are TypeSafe's own, forwarded verbatim:
+ *
+ * - `typesafe`: `POST {baseUrl}/v1/systemone` — TypeSafe and every System One
+ *   server (OpenJEV, Kev, self-hosted Clef, OpenCode Zen, Command Code).
+ * - `openrouter-decisions`: `POST {baseUrl}/decisions` under OpenRouter's
+ *   `/api/alpha`; usage adds the billed `cost` in USD.
+ * - `workers-ai-systemone`: Cloudflare Workers AI's `POST {baseUrl}/{model}`
+ *   (`/client/v4/accounts/<account>/ai/run/@cf/cloudflare/clef`). The body
+ *   names the model by its last path segment (`clef`), the response arrives in
+ *   Cloudflare's `{ result, success, errors }` envelope, and the credential is
+ *   a Cloudflare API token plus the account id the URL needs.
+ */
+import { parseCloudflareCredential } from "@oh-my-pi/pi-catalog/wire/cloudflare";
+import { $env, isRecord } from "@oh-my-pi/pi-utils";
+import * as AIError from "../error";
+import { tokenUsage } from "./types";
+import { type DecodedJudgment, finiteNumber, type JudgmentWire } from "./wire";
+
+function decodeSystemOne(payload: unknown): DecodedJudgment | undefined {
+	if (!isRecord(payload) || !isRecord(payload.answers)) return undefined;
+	const usage = isRecord(payload.usage) ? payload.usage : {};
+	return {
+		model: typeof payload.model === "string" ? payload.model : undefined,
+		answers: payload.answers,
+		refused: [],
+		usage: tokenUsage(finiteNumber(usage.input_tokens), finiteNumber(usage.output_tokens), finiteNumber(usage.cost)),
+	};
+}
+
+/** A System One dialect posting the verbatim request to `path` under the base URL with the key as bearer. */
+function systemOneWire(path: string): JudgmentWire {
+	return {
+		target: (baseUrl, _model, key) => ({ url: `${baseUrl}${path}`, token: key }),
+		encode: (request, model) => ({ state: request.state, model, questions: request.questions }),
+		decode: decodeSystemOne,
+	};
+}
+
+/** TypeSafe's own route, shared by every System One server. */
+export const typesafeWire = systemOneWire("/v1/systemone");
+
+/** OpenRouter Decisions: the System One body under `/api/alpha`. */
+export const openrouterDecisionsWire = systemOneWire("/decisions");
+
+/** Cloudflare Workers AI decision models (Clef) through the account-scoped `ai/run` route. */
+export const workersAiWire: JudgmentWire = {
+	target(baseUrl, model, key) {
+		const credential = parseCloudflareCredential(key);
+		const accountId = credential?.accountId ?? $env.CLOUDFLARE_ACCOUNT_ID?.trim();
+		if (!accountId) {
+			throw new AIError.ConfigurationError(
+				"Cloudflare account ID is required: log in to Cloudflare Workers AI again or set CLOUDFLARE_ACCOUNT_ID",
+			);
+		}
+		return { url: `${baseUrl.replace("<account>", accountId)}/${model}`, token: credential?.token ?? key };
+	},
+	encode: (request, model) => ({
+		state: request.state,
+		model: model.slice(model.lastIndexOf("/") + 1),
+		questions: request.questions,
+	}),
+	decode: payload => (isRecord(payload) ? decodeSystemOne(payload.result) : undefined),
+};

package/src/judgment/types.ts

@@ -7,7 +7,7 @@
  * — 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
+ * backend ({@link NativeJudge}) forwards requests verbatim, while the text
  * bridge ({@link TextJudge}) renders the same questions into keyword prompts
  * for an ordinary chat model.
  */
@@ -83,7 +83,7 @@ export interface JudgmentRequest<Q extends Questions = Questions> {
 }
 
 export interface JudgmentResult<Q extends Questions = Questions> {
-	/** Transport that produced the answers (`typesafe`, or the chat model's api). */
+	/** Transport that produced the answers (a judgment api such as `typesafe`, or the chat model's api). */
 	api: string;
 	provider: string;
 	model: string;

package/src/judgment/wire.ts

@@ -0,0 +1,42 @@
+/**
+ * Wire dialects of the native judgment APIs: how {@link NativeJudge} addresses,
+ * encodes, and decodes one request for each API it serves. Internal to the
+ * judgment module; `native.ts` maps every judgment API to its dialect.
+ */
+import type { Usage } from "../types";
+import type { JudgmentRequest } from "./types";
+
+/** Where one attempt posts and which bearer token it sends. */
+export interface JudgmentTarget {
+	url: string;
+	token: string;
+}
+
+/** One decoded response. */
+export interface DecodedJudgment {
+	/** Model that answered, when the response names one. */
+	model: string | undefined;
+	/** Wire answers keyed by question id; {@link NativeJudge} checks each against its question's type. */
+	answers: Readonly<Record<string, unknown>>;
+	/** Question ids the model declined to answer. */
+	refused: readonly string[];
+	usage: Usage;
+}
+
+/** How one judgment API addresses, encodes, and decodes a request. */
+export interface JudgmentWire {
+	/**
+	 * Target of one attempt made with credential `key` against `model`.
+	 * Throws when the credential cannot address the endpoint (e.g. no account id).
+	 */
+	target(baseUrl: string, model: string, key: string): JudgmentTarget;
+	/** Request body for `model`. */
+	encode(request: JudgmentRequest, model: string): unknown;
+	/** The response's answers and usage; `undefined` when the payload is not this API's response shape. */
+	decode(payload: unknown): DecodedJudgment | undefined;
+}
+
+/** `value` when it is a finite number. */
+export function finiteNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}