@orkestrel/agent 0.0.25 → 0.0.27

package/dist/src/core/index.cjs

@@ -146,6 +146,8 @@ var INVALID_RELAY_STATUS = 400;
 * carried with no body and answered for an aborted inbound read as well.
 */
 var OVERSIZED_RELAY_STATUS = 413;
+/** Names the System One decision endpoint shared by compatible servers. */
+var SYSTEM_ONE_PATH = "/v1/systemone";
 //#endregion
 //#region src/core/errors.ts
 /**
@@ -361,6 +363,75 @@ var ProviderError = class extends Error {
 function isProviderError(value) {
 	return (0, _orkestrel_contract.isInstance)(value, ProviderError);
 }
+/**
+* Reports a judge call cancelled by the caller's signal or its deadline, carrying the
+* {@link JudgeResult} merged from the calls that completed before the cancel and the
+* machine-readable `code` `'ABORT'`.
+*
+* @remarks
+* `partial` keeps the answers and the usage of every completed call, so usage reported by
+* completed calls is retained; a cancel before the first call carries an empty partial. `cause` holds the failure the
+* cancel superseded when a throw raced the abort, and is undefined when the cancel was the only
+* failure.
+*/
+var JudgeAbortError = class extends Error {
+	/** Names the machine-readable condition — `'ABORT'`: a judge call cancelled mid-flight. */
+	code = "ABORT";
+	partial;
+	constructor(partial, options) {
+		super("judge call aborted", options);
+		this.name = "JudgeAbortError";
+		this.partial = partial;
+	}
+};
+/**
+* Narrows a caught value to a {@link JudgeAbortError} through `instanceof`, so a `catch` can
+* recover its `partial` result.
+*
+* @param value - The caught value
+* @returns True if the value is a {@link JudgeAbortError}; false otherwise
+* @example
+* ```ts
+* isJudgeAbortError(new JudgeAbortError({ model: 'tev1:0.8b', answers: {} })) // true
+* ```
+*/
+function isJudgeAbortError(value) {
+	return (0, _orkestrel_contract.isInstance)(value, JudgeAbortError);
+}
+/**
+* Reports a coded judge failure with its HTTP status and underlying cause when available.
+*
+* @remarks
+* The judge engine throws this error for a non-OK HTTP response, a missing or unparsable
+* response body, and a request refused before inference. Concrete wire decoders also use it for
+* a response they cannot read and for a wire limit. `status` is present only for an `HTTP`
+* failure; other codes leave it undefined.
+*/
+var JudgeError = class extends Error {
+	/** Names the machine-readable condition — `'HTTP'`: a non-OK response; `'PROTOCOL'`: a missing, unparsable, or unreadable response body; `'QUESTION'`: a request refused before inference. */
+	code;
+	/** Holds the response status for an HTTP failure, or undefined for other codes. */
+	status;
+	constructor(code, message, options) {
+		super(message, options);
+		this.name = "JudgeError";
+		this.code = code;
+		this.status = options?.status;
+	}
+};
+/**
+* Narrows a caught value to the judge failure class through `instanceof`.
+*
+* @param value - The caught value
+* @returns True if the value is a {@link JudgeError}; false otherwise
+* @example
+* ```ts
+* isJudgeError(new JudgeError('HTTP', 'judge error: 429', { status: 429 })) // true
+* ```
+*/
+function isJudgeError(value) {
+	return (0, _orkestrel_contract.isInstance)(value, JudgeError);
+}
 //#endregion
 //#region src/core/shapers.ts
 /**
@@ -1260,6 +1331,273 @@ async function* readChunks(body, signal) {
 		}
 	}
 }
+/**
+* Derives the winner, its probability, the published confidence, and a score answer's expected
+* level from a judge answer's distribution.
+*
+* @remarks
+* The winner is the first strictly greatest candidate in enumeration order: an option name in
+* criteria order, a level index, or `'false'` then `'true'` for a noul, so a noul of exactly 0.5
+* names `'false'`. Confidence follows the TypeSafe formulas, whatever confidence a server sent: a
+* choice reads `(max(p) - 1/n) / (1 - 1/n)`, a noul reads `|2p - 1|` (the choice formula at
+* n = 2), and a score reads `max(0, 1 - spread / even_spread)`, where `spread` sums each level's
+* probability times its distance from the winning level and `even_spread` is the mean distance
+* from the middle level. `score` is the expected level `sum(i * p_i)` and is set only for a score
+* answer.
+*
+* @param answer - The answer whose distribution is read
+* @returns The derived measures
+* @throws JudgeError Thrown with code `PROTOCOL` when a choice or score answer has fewer than 2
+* candidates, because the confidence formulas divide by the candidate count
+* @example
+* ```ts
+* computeReading({ form: 'choice', probabilities: { billing: 0.88, technical: 0.12, sales: 0 } })
+* // { winner: 'billing', probability: 0.88, confidence: 0.82 } to two decimals
+* computeReading({ form: 'score', probabilities: [0, 0.57, 0.43] })
+* // { winner: '1', probability: 0.57, confidence: 0.355, score: 1.43 } to three decimals
+* computeReading({ form: 'noul', noul: 0.5 }) // { winner: 'false', probability: 0.5, confidence: 0 }
+* ```
+*/
+function computeReading(answer) {
+	if (answer.form === "noul") {
+		const yes = answer.noul > .5;
+		return {
+			winner: yes ? "true" : "false",
+			probability: yes ? answer.noul : 1 - answer.noul,
+			confidence: Math.abs(2 * answer.noul - 1)
+		};
+	}
+	const candidates = answer.form === "choice" ? Object.entries(answer.probabilities) : answer.probabilities.map((probability, level) => [String(level), probability]);
+	const count = candidates.length;
+	if (count < 2) throw new JudgeError("PROTOCOL", "judge error: an answer needs at least 2 candidates");
+	let winner = "";
+	let index = 0;
+	let probability = -Infinity;
+	for (const [position, [name, candidate]] of candidates.entries()) if (candidate > probability) {
+		winner = name;
+		index = position;
+		probability = candidate;
+	}
+	if (answer.form === "choice") return {
+		winner,
+		probability,
+		confidence: (probability - 1 / count) / (1 - 1 / count)
+	};
+	let spread = 0;
+	let even = 0;
+	let score = 0;
+	for (const [level, candidate] of answer.probabilities.entries()) {
+		spread += candidate * Math.abs(level - index);
+		even += Math.abs(level - (count - 1) / 2);
+		score += level * candidate;
+	}
+	return {
+		winner,
+		probability,
+		confidence: Math.max(0, 1 - spread / (even / count)),
+		score
+	};
+}
+/**
+* Merges the results of a judge request's calls into one result.
+*
+* @remarks
+* Pure and total. Answers and refusals are joined by question id; `refusals` is omitted when no
+* call refused a question. Each call's usage passes through {@link sanitizeUsage} and the totals
+* add through {@link sumUsage}; `usage` is omitted when no call reported one. The model is the
+* first call's, or the given model when the list is empty, as the empty partial of a cancel
+* before the first call requires.
+*
+* @param model - The judge's configured model, reported when no call completed
+* @param results - The completed calls' results in call order
+* @returns The merged result
+* @example
+* ```ts
+* buildJudgeResult('tev1:0.8b', []) // { model: 'tev1:0.8b', answers: {} }
+* buildJudgeResult('jev-latest', [
+* 	{ model: 'jev-1.13.0', answers: { urgent: { form: 'noul', noul: 0.95 } } },
+* 	{ model: 'jev-1.13.0', answers: {}, refusals: { team: { missing: ['sales'] } } },
+* ])
+* // { model: 'jev-1.13.0', answers: { urgent: ... }, refusals: { team: { missing: ['sales'] } } }
+* ```
+*/
+function buildJudgeResult(model, results) {
+	let answers = {};
+	let refusals = {};
+	let usage;
+	for (const result of results) {
+		answers = {
+			...answers,
+			...result.answers
+		};
+		refusals = {
+			...refusals,
+			...result.refusals
+		};
+		if (result.usage !== void 0) usage = sumUsage(usage, sanitizeUsage(result.usage));
+	}
+	return {
+		model: results[0]?.model ?? model,
+		answers,
+		...Object.keys(refusals).length === 0 ? {} : { refusals },
+		...usage === void 0 ? {} : { usage }
+	};
+}
+/**
+* Builds a request's JSON headers, awaiting the caller's header hook inside the call's
+* cancellation bound.
+*
+* @remarks
+* The headers start with `Content-Type: application/json`; each entry the hook returns is set
+* over them, so the hook overrides the content type only when it returns that header. The hook
+* receives `signal` and races its abort, and the abort listener is removed on every exit. Both
+* HTTP engines, the provider and the judge, read their headers here.
+*
+* @param hook - The caller's header hook, or undefined for the JSON content type alone
+* @param signal - The call's combined caller and deadline signal
+* @returns The request headers
+* @throws Thrown when the signal aborts before the hook settles, with the signal's reason, and
+* when the hook throws or rejects, with the hook's own failure
+* @example
+* ```ts
+* const signal = new AbortController().signal
+* const headers = await readHeaders(() => ({ authorization: 'Bearer KEY' }), signal)
+* headers.get('authorization') // 'Bearer KEY'
+* headers.get('content-type') // 'application/json'
+* ```
+*/
+async function readHeaders(hook, signal) {
+	const headers = new Headers({ "Content-Type": "application/json" });
+	if (hook === void 0) return headers;
+	const cleanup = new AbortController();
+	const aborted = Promise.withResolvers();
+	signal.addEventListener("abort", () => aborted.reject(signal.reason), {
+		once: true,
+		signal: cleanup.signal
+	});
+	try {
+		signal.throwIfAborted();
+		const entries = await Promise.race([Promise.resolve().then(() => hook(signal)), aborted.promise]);
+		for (const [key, value] of Object.entries(entries)) headers.set(key, value);
+		return headers;
+	} finally {
+		cleanup.abort();
+	}
+}
+/**
+* Owns a value by serializing it to JSON and parsing the text, so the copy shares nothing with its source.
+*
+* @remarks
+* A value that JSON cannot carry, such as a cycle or a bigint, and a value that serializes to
+* nothing, such as a function, both return undefined, so a guard over the result refuses them.
+* A proxied value serializes through its traps, where a structured clone refuses it.
+*
+* @param value - The value to own
+* @returns The owned JSON copy, or undefined when the value is not JSON
+* @example
+* ```ts
+* copyJSON({ state: 'A ticket.' }) // { state: 'A ticket.' }
+* copyJSON(() => 1) // undefined
+* ```
+*/
+function copyJSON(value) {
+	const text = (0, _orkestrel_contract.attempt)(() => JSON.stringify(value));
+	if (!text.success || typeof text.value !== "string") return void 0;
+	return (0, _orkestrel_contract.parseJSON)(text.value);
+}
+/**
+* Projects a judge question onto the System One wire while preserving omitted members.
+*
+* @param question - The domain question to send
+* @returns The wire question with `type` replacing `form`
+* @example
+* ```ts
+* questionToSystemOne({ form: 'noul' }) // { type: 'noul' }
+* ```
+*/
+function questionToSystemOne(question) {
+	return {
+		type: question.form,
+		...question.instructions === void 0 ? {} : { instructions: question.instructions },
+		...question.criteria === void 0 ? {} : { criteria: question.criteria }
+	};
+}
+/**
+* Extracts a System One distribution in question criteria order and drops server measures.
+*
+* @remarks
+* Every requested candidate must have a finite probability in [0, 1]; the helper checks each
+* requested candidate itself and reads no other member. Score maps and arrays project onto the
+* requested levels. Additional candidates are ignored, sums are unconstrained, and probabilities
+* are preserved without normalization.
+*
+* @param answer - The wire answer to decode
+* @param question - The question defining the form and candidate order
+* @returns The domain answer, or undefined for a mismatched form or a requested candidate whose
+* probability is missing, not finite, or outside [0, 1]
+* @example
+* ```ts
+* extractSystemOneAnswer({ type: 'noul', noul: 0.9 }, { form: 'noul' })
+* // { form: 'noul', noul: 0.9 }
+* ```
+*/
+function extractSystemOneAnswer(answer, question) {
+	const bounded = (0, _orkestrel_contract.boundsOf)(0, 1);
+	if (answer.type === "noul" && question.form === "noul") return bounded(answer.noul) ? {
+		form: "noul",
+		noul: answer.noul
+	} : void 0;
+	if (answer.type === "choice" && question.form === "choice") {
+		const entries = [];
+		for (const label of Object.keys(question.criteria)) {
+			if (!Object.hasOwn(answer.probabilities, label)) return void 0;
+			const probability = answer.probabilities[label];
+			if (!bounded(probability)) return void 0;
+			entries.push([label, probability]);
+		}
+		return {
+			form: "choice",
+			probabilities: Object.fromEntries(entries)
+		};
+	}
+	if (answer.type !== "score" || question.form !== "score") return void 0;
+	const probabilities = [];
+	for (let level = 0; level < question.criteria.length; level++) {
+		if (!Object.hasOwn(answer.probabilities, level)) return void 0;
+		const probability = (0, _orkestrel_contract.isArray)(answer.probabilities) ? answer.probabilities[level] : answer.probabilities[String(level)];
+		if (!bounded(probability)) return void 0;
+		probabilities.push(probability);
+	}
+	return {
+		form: "score",
+		probabilities
+	};
+}
+/**
+* Maps complete System One token counts onto validated token usage.
+*
+* @param usage - The optional wire token counts
+* @returns Token usage, or undefined for missing, null, negative, or non-finite counts
+* @example
+* ```ts
+* extractSystemOneUsage({ input_tokens: 975, output_tokens: 4 })
+* // { prompt: 975, completion: 4, total: 979 }
+* ```
+*/
+function extractSystemOneUsage(usage) {
+	const extracted = (0, _orkestrel_contract.attempt)(() => {
+		if (usage === void 0) return void 0;
+		const { input_tokens: prompt, output_tokens: completion } = usage;
+		if (!(0, _orkestrel_contract.isNumber)(prompt) || !(0, _orkestrel_contract.isNumber)(completion)) return void 0;
+		const result = {
+			prompt,
+			completion,
+			total: prompt + completion
+		};
+		return (0, _orkestrel_budget.isTokenUsage)(result) ? result : void 0;
+	});
+	return extracted.success ? extracted.value : void 0;
+}
 //#endregion
 //#region src/core/conversations/Conversation.ts
 /**
@@ -2190,7 +2528,7 @@ var Agent = class {
 					};
 					const toolMessage = this.#context.messages.add({
 						role: "tool",
-						content: outcomeResult.success ? JSON.stringify(outcomeResult.value) : outcomeResult.error
+						content: outcomeResult.success ? typeof outcomeResult.value === "string" ? outcomeResult.value : JSON.stringify(outcomeResult.value) : outcomeResult.error
 					});
 					messages.push(toolMessage);
 				}
@@ -2550,6 +2888,117 @@ function isConversationSnapshot(value) {
 	if (!(0, _orkestrel_contract.isArray)(value.sections) || !value.sections.every(isSection)) return false;
 	return (0, _orkestrel_contract.isArray)(value.messages) && value.messages.every(isMessage);
 }
+/**
+* Checks whether a value is a judge entry: a string, a JSON record, or a JSON array.
+*
+* @remarks
+* Total: a cycle, a non-JSON member, a class instance, and a hostile input return false. `null`
+* is not an entry; a criteria guard admits it where the protocol keeps it.
+*
+* @param value - The unknown entry candidate
+* @returns True if the value is a string or JSON structure the model can read; false otherwise
+* @example
+* ```ts
+* isJudgeEntry('Customer asks for a refund') // true
+* isJudgeEntry({ ticket: 4182, tags: ['billing'] }) // true
+* isJudgeEntry(null) // false
+* isJudgeEntry({ opened: new Date() }) // false
+* ```
+*/
+function isJudgeEntry(value) {
+	if ((0, _orkestrel_contract.isString)(value)) return true;
+	return ((0, _orkestrel_contract.isRecord)(value) || (0, _orkestrel_contract.isArray)(value)) && (0, _orkestrel_contract.isJSONValue)(value);
+}
+/**
+* Checks whether a value is a well-formed judge question of the choice, score, or noul form.
+*
+* @remarks
+* Total: a hostile input returns false. A choice needs at least 2 options and a score at least 2
+* levels, because the confidence formula divides by the candidate count; a description or a level
+* can be `null`. `instructions` and noul `criteria` are omitted when absent and never `null`.
+* Server limits on option, level, and question counts are left to the server.
+*
+* @param value - The unknown question candidate
+* @returns True if the value is a question the judge engine can send; false otherwise
+* @example
+* ```ts
+* isJudgeQuestion({ form: 'choice', criteria: { billing: null, bug: 'Software defect' } }) // true
+* isJudgeQuestion({ form: 'score', criteria: ['Cosmetic', null, 'Blocking'] }) // true
+* isJudgeQuestion({ form: 'noul', instructions: 'Is a refund owed?' }) // true
+* isJudgeQuestion({ form: 'choice', criteria: { billing: null } }) // false
+* ```
+*/
+function isJudgeQuestion(value) {
+	const checked = (0, _orkestrel_contract.attempt)(() => {
+		if (!(0, _orkestrel_contract.isRecord)(value)) return false;
+		const { form, instructions, criteria } = value;
+		if (instructions !== void 0 && !isJudgeEntry(instructions)) return false;
+		if (form === "choice") return (0, _orkestrel_contract.isRecord)(criteria) && Object.keys(criteria).length >= 2 && Object.values(criteria).every((0, _orkestrel_contract.nullableOf)(isJudgeEntry));
+		if (form === "score") return (0, _orkestrel_contract.arrayOf)((0, _orkestrel_contract.nullableOf)(isJudgeEntry))(criteria) && criteria.length >= 2;
+		if (form !== "noul") return false;
+		if (criteria === void 0) return true;
+		if (!(0, _orkestrel_contract.isRecord)(criteria)) return false;
+		return (0, _orkestrel_contract.optionalOf)(isJudgeEntry)(criteria.true) && (0, _orkestrel_contract.optionalOf)(isJudgeEntry)(criteria.false);
+	});
+	return checked.success && checked.value;
+}
+/**
+* Checks whether a value is a System One response envelope with optional model and usage.
+*
+* @remarks
+* Answers remain unknown until checked against their questions. Missing and null usage counts
+* are accepted. Extra members are ignored, and unreadable fields return false.
+*
+* @param value - The unknown response candidate
+* @returns True if the envelope fields have their wire types; false otherwise
+* @example
+* ```ts
+* isSystemOneResponse({ answers: {}, usage: { input_tokens: null } }) // true
+* ```
+*/
+function isSystemOneResponse(value) {
+	const checked = (0, _orkestrel_contract.attempt)(() => {
+		if (!(0, _orkestrel_contract.isRecord)(value)) return false;
+		const { model, answers, usage } = value;
+		if (!(0, _orkestrel_contract.optionalOf)(_orkestrel_contract.isString)(model) || !(0, _orkestrel_contract.isRecord)(answers)) return false;
+		if (usage === void 0) return true;
+		if (!(0, _orkestrel_contract.isRecord)(usage)) return false;
+		return (0, _orkestrel_contract.optionalOf)((0, _orkestrel_contract.nullableOf)(_orkestrel_contract.isNumber))(usage.input_tokens) && (0, _orkestrel_contract.optionalOf)((0, _orkestrel_contract.nullableOf)(_orkestrel_contract.isNumber))(usage.output_tokens);
+	});
+	return checked.success && checked.value;
+}
+/**
+* Checks whether a value is a System One answer whose type and distribution the wire can read.
+*
+* @remarks
+* The guard checks `type` and the distribution the wire dereferences: the `noul` number for a
+* noul, the `probabilities` map for a choice, and the `probabilities` map or dense array for a
+* score, each probability a finite number in [0, 1]. The `choice`, `score`, `confidence`, and
+* `legend` members are carried unchecked, because the wire never reads them, so a value this
+* guard accepts can hold any value in those members. Distribution sums are not constrained;
+* values are never normalized. Hostile reads return false.
+*
+* @param value - The unknown answer candidate
+* @returns True if the type and the distribution satisfy the wire contract; false otherwise
+* @example
+* ```ts
+* isSystemOneAnswer({ type: 'noul', noul: 0.9 }) // true
+* isSystemOneAnswer({ type: 'score', probabilities: [0.2, 0.8] }) // true
+* isSystemOneAnswer({ type: 'noul', noul: 1.1 }) // false
+* ```
+*/
+function isSystemOneAnswer(value) {
+	const checked = (0, _orkestrel_contract.attempt)(() => {
+		if (!(0, _orkestrel_contract.isRecord)(value)) return false;
+		const { type } = value;
+		if (type === "noul") return (0, _orkestrel_contract.boundsOf)(0, 1)(value.noul);
+		if (type !== "choice" && type !== "score") return false;
+		const { probabilities } = value;
+		if (type === "score" && (0, _orkestrel_contract.isArray)(probabilities)) return (0, _orkestrel_contract.arrayOf)((0, _orkestrel_contract.boundsOf)(0, 1))(probabilities);
+		return (0, _orkestrel_contract.isRecord)(probabilities) && Object.values(probabilities).every((0, _orkestrel_contract.boundsOf)(0, 1));
+	});
+	return checked.success && checked.value;
+}
 //#endregion
 //#region src/core/conversations/stores/DatabaseConversationStore.ts
 /**
@@ -2901,7 +3350,7 @@ var AgentProvider = class {
 		};
 	}
 	async #request(request, signal) {
-		const headers = await this.#requestHeaders(signal);
+		const headers = await readHeaders(this.#headers, signal);
 		signal.throwIfAborted();
 		const response = await this.#transport(this.#url + this.#path, {
 			method: "POST",
@@ -2924,25 +3373,6 @@ var AgentProvider = class {
 		}
 		return response;
 	}
-	async #requestHeaders(signal) {
-		const headers = new Headers({ "Content-Type": "application/json" });
-		if (this.#headers === void 0) return headers;
-		const cleanup = new AbortController();
-		const aborted = Promise.withResolvers();
-		signal.addEventListener("abort", () => aborted.reject(signal.reason), {
-			once: true,
-			signal: cleanup.signal
-		});
-		try {
-			signal.throwIfAborted();
-			const hook = this.#headers;
-			const entries = await Promise.race([Promise.resolve().then(() => hook(signal)), aborted.promise]);
-			for (const [key, value] of Object.entries(entries)) headers.set(key, value);
-			return headers;
-		} finally {
-			cleanup.abort();
-		}
-	}
 };
 //#endregion
 //#region src/core/providers/RelayProvider.ts
@@ -3089,6 +3519,258 @@ var RelayProvider = class extends AgentProvider {
 	}
 };
 //#endregion
+//#region src/core/AgentJudge.ts
+/**
+* Implements the bounded HTTP calls, validation, and result merging of a judge behind concrete
+* wire seams.
+*
+* @remarks
+* A subclass fills `name`, `body`, and `read`; the constructor takes the `batch` switch that
+* decides whether one call carries every question or each question gets its own call in key
+* order. `ask` validates the request before any call, builds every body before the first call so
+* a wire limit refuses the request before inference, and runs the calls one after another, each
+* under its own deadline folded with the caller's signal. A cancel throws a `JudgeAbortError`
+* whose `partial` merges the calls that completed. A transport error reaches the caller unchanged.
+*
+* @example Writing a judge wire
+* ```ts
+* import type { JudgeRequest, JudgeResult } from '@orkestrel/agent'
+* import { AgentJudge, JudgeError } from '@orkestrel/agent'
+* import { isFiniteNumber, isRecord } from '@orkestrel/contract'
+*
+* // A wire whose server answers one yes/no question per call as { "yes": 0.93 }.
+* class YesJudge extends AgentJudge {
+* 	readonly name = 'yes'
+* 	body(request: JudgeRequest): object {
+* 		return { model: this.model, state: request.state, questions: request.questions }
+* 	}
+* 	read(value: unknown, request: JudgeRequest): JudgeResult {
+* 		const [id] = Object.keys(request.questions)
+* 		if (id === undefined || !isRecord(value) || !isFiniteNumber(value.yes)) {
+* 			throw new JudgeError('PROTOCOL', 'judge error: unreadable answer')
+* 		}
+* 		return { model: this.model, answers: { [id]: { form: 'noul', noul: value.yes } } }
+* 	}
+* }
+*
+* const judge = new YesJudge({
+* 	url: 'http://localhost:8010',
+* 	path: '/v1/yes',
+* 	model: 'yes-1',
+* 	batch: false,
+* })
+* ```
+*/
+var AgentJudge = class {
+	#id;
+	#url;
+	#path;
+	#model;
+	#timeout;
+	#transport;
+	#headers;
+	#batch;
+	constructor(input) {
+		this.#id = crypto.randomUUID();
+		this.#url = input.url;
+		this.#path = input.path ?? "";
+		this.#model = input.model;
+		this.#timeout = input.timeout ?? 12e4;
+		this.#transport = input.fetch ?? globalThis.fetch.bind(globalThis);
+		this.#headers = input.headers;
+		this.#batch = input.batch ?? true;
+	}
+	/** Exposes the instance's minted UUID. */
+	get id() {
+		return this.#id;
+	}
+	/** Exposes the configured model identity. */
+	get model() {
+		return this.#model;
+	}
+	/**
+	* Asks every question of the request about its state and merges the answers of every call.
+	*
+	* @param request - The state and the questions keyed by caller id
+	* @param signal - The caller's cancellation bound
+	* @returns The merged answers, refusals, and usage of every call
+	* @throws JudgeAbortError Thrown when the caller's signal or a call's deadline fires, carrying
+	* the merged result of the completed calls
+	* @throws JudgeError Thrown with code `QUESTION` for an empty question map, a malformed question
+	* or state, or a wire refusal before any call; with code `HTTP` for a non-OK response; and with
+	* code `PROTOCOL` for a missing or unparsable response body
+	*/
+	async ask(request, signal) {
+		if (signal.aborted) throw new JudgeAbortError(buildJudgeResult(this.#model, []));
+		const state = copyJSON(request.state);
+		if (!isJudgeEntry(state)) throw new JudgeError("QUESTION", "judge error: state is not a judge entry");
+		const questions = (0, _orkestrel_contract.isRecord)(request.questions) ? Object.entries(request.questions) : [];
+		if (questions.length === 0) throw new JudgeError("QUESTION", "judge error: no questions");
+		const entries = [];
+		for (const [id, question] of questions) {
+			const copy = copyJSON(question);
+			if (!isJudgeQuestion(copy)) throw new JudgeError("QUESTION", `judge error: question ${id} is malformed`);
+			entries.push([id, copy]);
+		}
+		const owned = {
+			state,
+			questions: Object.fromEntries(entries)
+		};
+		const calls = (this.#batch ? [owned] : entries.map(([id, question]) => ({
+			state,
+			questions: { [id]: question }
+		}))).map((part) => ({
+			request: part,
+			body: JSON.stringify(this.body(part))
+		}));
+		const results = [];
+		for (const call of calls) results.push(await this.#call(call.request, call.body, signal, results));
+		return buildJudgeResult(this.#model, results);
+	}
+	async #call(request, body, signal, completed) {
+		const timeout = new _orkestrel_timeout.Timeout({ ms: this.#timeout });
+		timeout.start();
+		const combined = AbortSignal.any([timeout.signal, signal]);
+		try {
+			const headers = await readHeaders(this.#headers, combined);
+			combined.throwIfAborted();
+			const response = await this.#transport(this.#url + this.#path, {
+				method: "POST",
+				headers,
+				body,
+				signal: combined
+			});
+			if (!response.ok) {
+				let detail;
+				try {
+					detail = response.body === null ? "" : (await readText(response.body, MAX_ERROR_BODY_LENGTH, combined)).text;
+				} catch (cause) {
+					throw new JudgeError("HTTP", `judge error: ${response.status} - (error body unavailable)`, {
+						status: response.status,
+						cause
+					});
+				}
+				combined.throwIfAborted();
+				throw new JudgeError("HTTP", `judge error: ${response.status}${detail === "" ? "" : ` - ${detail}`}`, { status: response.status });
+			}
+			if (response.body === null) throw new JudgeError("PROTOCOL", "judge error: no response body");
+			const text = await readText(response.body, void 0, combined);
+			combined.throwIfAborted();
+			const value = (0, _orkestrel_contract.parseJSON)(text.text);
+			if (value === void 0) throw new JudgeError("PROTOCOL", "judge error: invalid JSON body");
+			const result = this.read(value, request);
+			combined.throwIfAborted();
+			return result;
+		} catch (error) {
+			if (combined.aborted) throw new JudgeAbortError(buildJudgeResult(this.#model, completed), error === combined.reason ? void 0 : { cause: error });
+			throw error;
+		} finally {
+			timeout.clear();
+		}
+	}
+};
+//#endregion
+//#region src/core/providers/SystemOneJudge.ts
+/**
+* Carries judge questions over the System One protocol and derives answers from server distributions.
+*
+* @remarks
+* The caller supplies the server origin and model. Every question travels in one request.
+* Server measures are ignored; the response model is preserved.
+* `headers` supplies authentication through the shared judge engine.
+*
+* @example Asking a System One server a choice, a noul, and a score
+* ```ts
+* import { computeReading, createSystemOneJudge } from '@orkestrel/agent'
+*
+* const judge = createSystemOneJudge({ url: 'http://localhost:11434', model: 'tev1:0.8b' })
+* const result = await judge.ask(
+* 	{
+* 		state: 'Our checkout has returned 500 errors since 9am. I want a refund for today.',
+* 		questions: {
+* 			label: {
+* 				form: 'choice',
+* 				instructions: 'Which label fits this ticket?',
+* 				criteria: { billing: 'Payments and refunds', bug: 'Software errors', account: null },
+* 			},
+* 			refund: {
+* 				form: 'noul',
+* 				instructions: 'Does the customer ask for money back?',
+* 				criteria: {
+* 					true: 'The customer asks for a refund or for money back.',
+* 					false: 'The customer does not ask for money back.',
+* 				},
+* 			},
+* 			severity: {
+* 				form: 'score',
+* 				instructions: 'How severe is the reported issue?',
+* 				criteria: ['Cosmetic; no impact', 'Degraded, workaround exists', 'Blocking; no workaround'],
+* 			},
+* 		},
+* 	},
+* 	AbortSignal.timeout(30_000),
+* )
+* const readings = Object.fromEntries(
+* 	Object.entries(result.answers).map(([id, answer]) => [id, computeReading(answer)]),
+* )
+* result.model // 'tev1:0.8b' — the model the server named
+* result.usage // { prompt: 975, completion: 4, total: 979 }
+* readings.label // { winner: 'bug', probability: 0.9691, confidence: 0.9536 } to four decimals
+* readings.refund // { winner: 'true', probability: 0.9979, confidence: 0.9958 } to four decimals
+* readings.severity // { winner: '1', probability: 0.9494, confidence: 0.9241, score: 0.9919 } to four decimals
+* ```
+*/
+var SystemOneJudge = class extends AgentJudge {
+	constructor(options) {
+		super({
+			...options,
+			path: SYSTEM_ONE_PATH,
+			batch: true
+		});
+	}
+	/** Identifies the System One protocol. */
+	name = "systemone";
+	/**
+	* Projects the state and questions onto the System One request with the configured model.
+	*
+	* @param request - The state and questions keyed by caller id
+	* @returns The System One request body
+	*/
+	body(request) {
+		return {
+			state: request.state,
+			model: this.model,
+			questions: Object.fromEntries(Object.entries(request.questions).map(([id, question]) => [id, questionToSystemOne(question)]))
+		};
+	}
+	/**
+	* Decodes requested System One answers and reports the server model and available usage.
+	*
+	* @param value - The parsed response body
+	* @param request - The questions defining the expected answers
+	* @returns The decoded distributions, model, and available usage
+	* @throws JudgeError Thrown with code `PROTOCOL` for a malformed envelope or an invalid answer naming its question id
+	*/
+	read(value, request) {
+		if (!isSystemOneResponse(value)) throw new JudgeError("PROTOCOL", "judge error: invalid System One response envelope");
+		const entries = [];
+		for (const [id, question] of Object.entries(request.questions)) {
+			if (!Object.hasOwn(value.answers, id)) throw new JudgeError("PROTOCOL", `judge error: question ${id} has no System One answer`);
+			const wire = value.answers[id];
+			if (!isSystemOneAnswer(wire)) throw new JudgeError("PROTOCOL", `judge error: question ${id} has an invalid System One answer`);
+			const answer = extractSystemOneAnswer(wire, question);
+			if (answer === void 0) throw new JudgeError("PROTOCOL", `judge error: question ${id} has a mismatched or incomplete System One answer`);
+			entries.push([id, answer]);
+		}
+		const usage = extractSystemOneUsage(value.usage);
+		return {
+			model: value.model ?? this.model,
+			answers: Object.fromEntries(entries),
+			...usage === void 0 ? {} : { usage }
+		};
+	}
+};
+//#endregion
 //#region src/core/RelayStream.ts
 /**
 * Streams a provider call as validated NDJSON frames under response backpressure.
@@ -4126,11 +4808,25 @@ function createAgentRunner(options) {
 		handler: handleAgentRunnerJob.bind(void 0, registry, partial)
 	});
 }
+/**
+* Creates a judge that sends every question through the configured System One server.
+*
+* @param options - The server origin, model, and optional transport, headers, and timeout
+* @returns The configured judge behind its shared interface
+* @example
+* ```ts
+* const judge = createSystemOneJudge({ url: 'http://localhost:11434', model: 'tev1:0.8b' })
+* ```
+*/
+function createSystemOneJudge(options) {
+	return new SystemOneJudge(options);
+}
 //#endregion
 exports.Agent = Agent;
 exports.AgentContext = AgentContext;
 exports.AgentError = AgentError;
 exports.AgentJobError = AgentJobError;
+exports.AgentJudge = AgentJudge;
 exports.AgentProvider = AgentProvider;
 exports.AgentRegistry = AgentRegistry;
 exports.Authority = Authority;
@@ -4149,6 +4845,8 @@ exports.IMAGE_TOKEN_ESTIMATE = IMAGE_TOKEN_ESTIMATE;
 exports.INVALID_RELAY_STATUS = INVALID_RELAY_STATUS;
 exports.Instruction = Instruction;
 exports.InstructionManager = InstructionManager;
+exports.JudgeAbortError = JudgeAbortError;
+exports.JudgeError = JudgeError;
 exports.MAX_ERROR_BODY_LENGTH = MAX_ERROR_BODY_LENGTH;
 exports.MESSAGE_TOKEN_OVERHEAD = MESSAGE_TOKEN_OVERHEAD;
 exports.MemoryConversationStore = MemoryConversationStore;
@@ -4159,8 +4857,10 @@ exports.RELAY_CONTENT_TYPE = RELAY_CONTENT_TYPE;
 exports.RELAY_PROVIDER_MESSAGE = RELAY_PROVIDER_MESSAGE;
 exports.RelayProvider = RelayProvider;
 exports.RelayStream = RelayStream;
+exports.SYSTEM_ONE_PATH = SYSTEM_ONE_PATH;
 exports.Scope = Scope;
 exports.ScopeManager = ScopeManager;
+exports.SystemOneJudge = SystemOneJudge;
 exports.THINK_CLOSE = THINK_CLOSE;
 exports.THINK_OPEN = THINK_OPEN;
 exports.ThinkSplitter = ThinkSplitter;
@@ -4171,10 +4871,13 @@ exports.agentResultToJSON = agentResultToJSON;
 exports.assembleResult = assembleResult;
 exports.attachImages = attachImages;
 exports.attachUserImages = attachUserImages;
+exports.buildJudgeResult = buildJudgeResult;
 exports.buildProviderResult = buildProviderResult;
 exports.buildRecapMessage = buildRecapMessage;
 exports.buildSummaryMessage = buildSummaryMessage;
 exports.collectImageData = collectImageData;
+exports.computeReading = computeReading;
+exports.copyJSON = copyJSON;
 exports.createAgent = createAgent;
 exports.createAgentContext = createAgentContext;
 exports.createAgentQueue = createAgentQueue;
@@ -4192,10 +4895,13 @@ exports.createRelay = createRelay;
 exports.createRelayProvider = createRelayProvider;
 exports.createScope = createScope;
 exports.createScopeManager = createScopeManager;
+exports.createSystemOneJudge = createSystemOneJudge;
 exports.createThinkSplitter = createThinkSplitter;
 exports.denyCall = denyCall;
 exports.estimateMessages = estimateMessages;
 exports.estimateTokens = estimateTokens;
+exports.extractSystemOneAnswer = extractSystemOneAnswer;
+exports.extractSystemOneUsage = extractSystemOneUsage;
 exports.filterAllowList = filterAllowList;
 exports.handleAgentQueueJob = handleAgentQueueJob;
 exports.handleAgentRunnerJob = handleAgentRunnerJob;
@@ -4204,10 +4910,16 @@ exports.isAgentError = isAgentError;
 exports.isAgentJobError = isAgentJobError;
 exports.isConversationError = isConversationError;
 exports.isConversationSnapshot = isConversationSnapshot;
+exports.isJudgeAbortError = isJudgeAbortError;
+exports.isJudgeEntry = isJudgeEntry;
+exports.isJudgeError = isJudgeError;
+exports.isJudgeQuestion = isJudgeQuestion;
 exports.isMessage = isMessage;
 exports.isProviderAbortError = isProviderAbortError;
 exports.isProviderError = isProviderError;
 exports.isSection = isSection;
+exports.isSystemOneAnswer = isSystemOneAnswer;
+exports.isSystemOneResponse = isSystemOneResponse;
 exports.joinThinking = joinThinking;
 exports.messageContract = messageContract;
 exports.messageShape = messageShape;
@@ -4215,7 +4927,9 @@ exports.providerRequestContract = providerRequestContract;
 exports.providerRequestShape = providerRequestShape;
 exports.providerResultContract = providerResultContract;
 exports.providerResultShape = providerResultShape;
+exports.questionToSystemOne = questionToSystemOne;
 exports.readChunks = readChunks;
+exports.readHeaders = readHeaders;
 exports.readText = readText;
 exports.relayFrameContract = relayFrameContract;
 exports.relayFrameShape = relayFrameShape;