@orkestrel/agent 0.0.25 → 0.0.27

package/dist/src/core/index.d.ts

@@ -9,6 +9,7 @@ import type { EmitterErrorHandler } from '@orkestrel/emitter';
 import type { EmitterHooks } from '@orkestrel/emitter';
 import type { EmitterInterface } from '@orkestrel/emitter';
 import type { FileInterface } from '@orkestrel/workspace';
+import type { JSONRecord } from '@orkestrel/contract';
 import { JSONShape } from '@orkestrel/contract';
 import { JSONValue } from '@orkestrel/contract';
 import { LiteralShape } from '@orkestrel/contract';
@@ -624,6 +625,99 @@ export declare interface AgentJobInput {
     readonly children?: readonly AgentJobInput[];
 }
 
+/**
+ * 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,
+ * })
+ * ```
+ */
+export declare abstract class AgentJudge implements AgentJudgeInterface {
+    #private;
+    constructor(input: AgentJudgeInput);
+    /** Identifies the concrete wire. */
+    abstract readonly name: string;
+    /** Exposes the instance's minted UUID. */
+    get id(): string;
+    /** Exposes the configured model identity. */
+    get model(): string;
+    /** Projects one call's request onto the concrete protocol's wire body. */
+    abstract body(request: JudgeRequest): object;
+    /** Decodes one call's parsed response body into the answers for that call's questions. */
+    abstract read(value: unknown, request: JudgeRequest): JudgeResult;
+    /**
+     * 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
+     */
+    ask(request: JudgeRequest, signal: AbortSignal): Promise<JudgeResult>;
+}
+
+/**
+ * Configures the judge engine's destination, identity, and call split.
+ *
+ * @remarks
+ * `path` appends to `url`. `model` is the identity the judge reports when a response names none.
+ * `timeout`, `fetch`, and `headers` bound, carry, and authenticate each call as they do for a
+ * provider; the deadline applies to each call on its own.
+ */
+export declare interface AgentJudgeInput extends Pick<ProviderOptions, 'timeout' | 'fetch' | 'headers'> {
+    readonly url: string;
+    readonly path?: string;
+    readonly model: string;
+    /** If true, one call carries every question; if false, the engine issues one call per question. Default: true. */
+    readonly batch?: boolean;
+}
+
+/** Defines the wire seams of the shared judge engine. */
+export declare interface AgentJudgeInterface extends JudgeInterface {
+    /** Projects one call's request onto the concrete protocol's serializable body. */
+    body(request: JudgeRequest): object;
+    /** Decodes one call's parsed response body into the answers for that call's questions. */
+    read(value: unknown, request: JudgeRequest): JudgeResult;
+}
+
 /**
  * Configures `createAgent` — the loop's bounds and pacing, the reserved `on` hooks, the
  * construction-time context wiring (`instructions` / `workspaces` / `scope`), the `conversations`
@@ -1350,6 +1444,31 @@ export declare interface AuthorityRule {
     readonly reason?: string;
 }
 
+/**
+ * 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'] } } }
+ * ```
+ */
+export declare function buildJudgeResult(model: string, results: readonly JudgeResult[]): JudgeResult;
+
 /**
  * Assembles a provider result with only populated optional fields.
  *
@@ -1482,6 +1601,22 @@ export declare interface ChannelInterface<T> {
     drain(): AsyncGenerator<T, void>;
 }
 
+/** Carries a choice distribution keyed by option name, in criteria order. */
+export declare interface ChoiceAnswer {
+    readonly form: 'choice';
+    readonly probabilities: Readonly<Record<string, number>>;
+}
+
+/** Maps each option name the model sees to its description; null keeps an undescribed option in the map. */
+export declare type ChoiceCriteria = Readonly<Record<string, JudgeEntry | null>>;
+
+/** Asks the model to pick one named option from its criteria. */
+export declare interface ChoiceQuestion {
+    readonly form: 'choice';
+    readonly instructions?: JudgeEntry;
+    readonly criteria: ChoiceCriteria;
+}
+
 /**
  * Collects the `base64` payload of the image files in a workspace file list — the data an agent
  * context attaches to the last user message.
@@ -1522,6 +1657,35 @@ export declare interface CompactOptions {
     readonly sections?: number;
 }
 
+/**
+ * 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 }
+ * ```
+ */
+export declare function computeReading(answer: JudgeAnswer): Reading;
+
 /**
  * Holds a provider's optional context-framing default, keyed by section kind — the framing a model
  * prefers (for example XML tags against Markdown headers), declared by a {@link ProviderInterface}
@@ -2343,6 +2507,24 @@ export declare interface ConversationStoreInterface {
  */
 export declare type ConversationSummaryHandler = (messages: readonly Message[]) => Promise<string>;
 
+/**
+ * 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
+ * ```
+ */
+export declare function copyJSON(value: unknown): unknown;
+
 /**
  * Creates an agent loop — an {@link AgentInterface} composing a
  * {@link ProviderInterface}, its {@link AgentContextInterface}, and a tool registry
@@ -2926,6 +3108,18 @@ export declare function createScope(input: ScopeInput): ScopeInterface;
  */
 export declare function createScopeManager(options?: ScopeManagerOptions): ScopeManagerInterface;
 
+/**
+ * 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' })
+ * ```
+ */
+export declare function createSystemOneJudge(options: SystemOneJudgeOptions): JudgeInterface;
+
 /**
  * Creates a fresh stream-stateful `<think>` separator — a {@link ThinkSplitterInterface} that
  * splits a thinking model's in-content `<think>…</think>` reasoning spans away from the answer,
@@ -3142,6 +3336,40 @@ export declare function estimateMessages(messages: readonly Message[]): number;
  */
 export declare function estimateTokens(text: string): number;
 
+/**
+ * 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 }
+ * ```
+ */
+export declare function extractSystemOneAnswer(answer: SystemOneAnswer, question: JudgeQuestion): JudgeAnswer | undefined;
+
+/**
+ * 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 }
+ * ```
+ */
+export declare function extractSystemOneUsage(usage: SystemOneUsage | undefined): TokenUsage | undefined;
+
 /**
  * Filters a list of items by a {@link import('./types.js').ScopeInterface} allow-list of keys —
  * `undefined` passes everything, `[]` passes nothing, and a non-empty list passes the listed keys
@@ -3556,6 +3784,71 @@ export declare function isConversationError(value: unknown): value is Conversati
  */
 export declare function isConversationSnapshot(value: unknown): value is ConversationSnapshot;
 
+/**
+ * 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
+ * ```
+ */
+export declare function isJudgeAbortError(value: unknown): value is JudgeAbortError;
+
+/**
+ * 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
+ * ```
+ */
+export declare function isJudgeEntry(value: unknown): value is JudgeEntry;
+
+/**
+ * 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
+ * ```
+ */
+export declare function isJudgeError(value: unknown): value is JudgeError;
+
+/**
+ * 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
+ * ```
+ */
+export declare function isJudgeQuestion(value: unknown): value is JudgeQuestion;
+
 /**
  * Checks whether a value satisfies the domain conversation-message contract.
  *
@@ -3629,6 +3922,44 @@ export declare function isProviderError(value: unknown): value is ProviderError;
  */
 export declare function isSection(value: unknown): value is Section;
 
+/**
+ * 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
+ * ```
+ */
+export declare function isSystemOneAnswer(value: unknown): value is SystemOneAnswer;
+
+/**
+ * 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
+ * ```
+ */
+export declare function isSystemOneResponse(value: unknown): value is SystemOneResponse;
+
 /**
  * Joins the reasoning a run's provider calls separated from the answer — the first call
  * seeds the accumulation, a later call appends blank-line separated so each turn's reasoning
@@ -3652,6 +3983,84 @@ export declare function isSection(value: unknown): value is Section;
  */
 export declare function joinThinking(running: string | undefined, next: string): string;
 
+/**
+ * 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.
+ */
+export declare class JudgeAbortError extends Error {
+    /** Names the machine-readable condition — `'ABORT'`: a judge call cancelled mid-flight. */
+    readonly code: "ABORT";
+    readonly partial: JudgeResult;
+    constructor(partial: JudgeResult, options?: ErrorOptions);
+}
+
+/** Names one answer by its form; it stores only the distribution a server returned. */
+export declare type JudgeAnswer = ChoiceAnswer | ScoreAnswer | NoulAnswer;
+
+/** Carries text or structured JSON the model reads; mirrors the TypeSafe `EntryType` without its null arm. */
+export declare type JudgeEntry = string | JSONRecord | readonly JSONValue[];
+
+/**
+ * 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.
+ */
+export declare class JudgeError 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. */
+    readonly code: JudgeErrorCode;
+    /** Holds the response status for an HTTP failure, or undefined for other codes. */
+    readonly status: number | undefined;
+    constructor(code: JudgeErrorCode, message: string, options?: ProviderErrorOptions);
+}
+
+/** Names the machine-readable judge failure conditions. */
+export declare type JudgeErrorCode = 
+/** Reports a non-OK HTTP response. */
+'HTTP'
+/** Reports a missing or unparsable response body, or a response a wire cannot read. */
+| 'PROTOCOL'
+/** Reports a request refused before inference: an empty question map, a malformed question or state, a wire limit, or a judge configuration that would refuse every request. */
+| 'QUESTION';
+
+/** Answers typed questions about one state with probabilities; the sibling of `ProviderInterface`, never a provider. */
+export declare interface JudgeInterface {
+    readonly id: string;
+    readonly name: string;
+    /** Holds the configured model identity; the wire composes it from everything that changes an answer under one state. */
+    readonly model: string;
+    /** Asks every question of the request about its state and returns the merged answers. */
+    ask(request: JudgeRequest, signal: AbortSignal): Promise<JudgeResult>;
+}
+
+/** Names one question by its form, the protocol's type field under the fleet's named discriminant. */
+export declare type JudgeQuestion = ChoiceQuestion | ScoreQuestion | NoulQuestion;
+
+/** Carries one state and the questions asked about it, keyed by caller ids the model never sees; each question is evaluated on its own. */
+export declare interface JudgeRequest {
+    readonly state: JudgeEntry;
+    readonly questions: Readonly<Record<string, JudgeQuestion>>;
+}
+
+/** Carries the answering model, the answers keyed by question id, the refusals, and the usage the request's calls spent. */
+export declare interface JudgeResult {
+    readonly model: string;
+    readonly answers: Readonly<Record<string, JudgeAnswer>>;
+    /** Holds each refused question by id; absent when none was refused. An id appears in answers or refusals, never both. */
+    readonly refusals?: Readonly<Record<string, Refusal>>;
+    readonly usage?: TokenUsage;
+}
+
 /**
  * Bounds the decoded error excerpt's input in bytes — `2048`, the leading bytes of a non-OK
  * response body handed to the decoder before the read cancels the remainder, so a `ProviderError`
@@ -3733,6 +4142,8 @@ export declare class MemoryConversationStore implements ConversationStoreInterfa
  * `tool_calls` a prior generation produced, replayed back into the next request so
  * the model sees its own decision. A `tool` turn carries the tool's result in
  * `content` (the textual outcome), keyed back to the call by the conversation order.
+ * For a successful tool result, a string is the content as is; any other value is
+ * JSON-encoded. A failed tool result carries its error text unchanged.
  */
 export declare interface Message {
     readonly id: string;
@@ -3848,6 +4259,25 @@ arguments: ObjectShape<Record<never, never>, JSONShape>;
 images: OptionalShape<ArrayShape<StringShape>>;
 }, boolean | ContractShape>;
 
+/** Carries the probability that the answer is yes; the protocol's noul field. */
+export declare interface NoulAnswer {
+    readonly form: 'noul';
+    readonly noul: number;
+}
+
+/** Carries what makes a noul answer true and what makes it false; an omitted side is undescribed. */
+export declare interface NoulCriteria {
+    readonly true?: JudgeEntry;
+    readonly false?: JudgeEntry;
+}
+
+/** Asks the model whether a statement about the state holds. */
+export declare interface NoulQuestion {
+    readonly form: 'noul';
+    readonly instructions?: JudgeEntry;
+    readonly criteria?: NoulCriteria;
+}
+
 /**
  * Names the status a relay answers for a request body at or above its byte budget — `413`,
  * carried with no body and answered for an aborted inbound read as well.
@@ -4179,6 +4609,18 @@ export declare interface ProviderStreamOptions {
     readonly schema?: Readonly<Record<string, unknown>>;
 }
 
+/**
+ * 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' }
+ * ```
+ */
+export declare function questionToSystemOne(question: JudgeQuestion): SystemOneQuestion;
+
 /**
  * Decodes UTF-8 chunks with a final flush and releases the stream on every exit.
  *
@@ -4193,6 +4635,41 @@ export declare interface ProviderStreamOptions {
  */
 export declare function readChunks(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<string>;
 
+/**
+ * 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'
+ * ```
+ */
+export declare function readHeaders(hook: ProviderOptions['headers'], signal: AbortSignal): Promise<Headers>;
+
+/** Carries the measures `computeReading` derives from an answer; nothing stores them. */
+export declare interface Reading {
+    /** Holds the first strictly greatest candidate in enumeration order: an option name, a level index, or true or false. */
+    readonly winner: string;
+    readonly probability: number;
+    readonly confidence: number;
+    /** Holds the expected level of a score answer; the protocol's score field. */
+    readonly score?: number;
+}
+
 /**
  * Reads a UTF-8 prefix of a byte stream and cancels its remainder.
  *
@@ -4216,6 +4693,11 @@ export declare function readChunks(body: ReadableStream<Uint8Array>, signal?: Ab
  */
 export declare function readText(body: ReadableStream<Uint8Array>, limit?: number, signal?: AbortSignal): Promise<TextRead>;
 
+/** Reports a question a wire could not read a candidate for; it lists the caller's keys and invents no probability. */
+export declare interface Refusal {
+    readonly missing: readonly string[];
+}
+
 /**
  * Names the relay's newline-delimited JSON content type — `'application/x-ndjson; charset=utf-8'`,
  * the header a relay response carries beside `cache-control: no-store`.
@@ -4858,6 +5340,26 @@ export declare interface ScopeManagerOptions {
     readonly error?: EmitterErrorHandler;
 }
 
+/** Carries a score distribution indexed by level. */
+export declare interface ScoreAnswer {
+    readonly form: 'score';
+    readonly probabilities: readonly number[];
+}
+
+/** Lists at least two score levels from level 0 upward; null leaves a level undescribed. */
+export declare type ScoreCriteria = readonly [
+JudgeEntry | null,
+JudgeEntry | null,
+...Array<JudgeEntry | null>
+];
+
+/** Asks the model to place the state on an ordered scale of levels. */
+export declare interface ScoreQuestion {
+    readonly form: 'score';
+    readonly instructions?: JudgeEntry;
+    readonly criteria: ScoreCriteria;
+}
+
 /**
  * Holds a slice of folded messages digested into a summary — the unit of compaction a
  * {@link ConversationInterface} produces when it `compact`s its live tail.
@@ -4949,6 +5451,144 @@ export declare interface StreamInterface<T, R> {
  */
 export declare function sumUsage(running: TokenUsage | undefined, next: TokenUsage): TokenUsage;
 
+/** Names the System One decision endpoint shared by compatible servers. */
+export declare const SYSTEM_ONE_PATH = "/v1/systemone";
+
+/** Unites the TypeSafe System One answer forms. */
+export declare type SystemOneAnswer = SystemOneChoiceAnswer | SystemOneScoreAnswer | SystemOneNoulAnswer;
+
+/** Transliterates a TypeSafe System One choice distribution and optional server measures. */
+export declare interface SystemOneChoiceAnswer {
+    readonly type: 'choice';
+    readonly probabilities: Readonly<Record<string, number>>;
+    readonly choice?: string;
+    readonly confidence?: number;
+}
+
+/** Carries a TypeSafe System One entry, including the wire's explicit null. */
+export declare type SystemOneEntry = JudgeEntry | null;
+
+/**
+ * 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
+ * ```
+ */
+export declare class SystemOneJudge extends AgentJudge {
+    constructor(options: SystemOneJudgeOptions);
+    /** Identifies the System One protocol. */
+    readonly 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: JudgeRequest): SystemOneRequest;
+    /**
+     * 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: unknown, request: JudgeRequest): JudgeResult;
+}
+
+/** Configures the System One server, model, transport, authentication, and deadline. */
+export declare interface SystemOneJudgeOptions extends Pick<ProviderOptions, 'timeout' | 'fetch' | 'headers'> {
+    /** Holds the server origin without a path. */
+    readonly url: string;
+    readonly model: string;
+}
+
+/** Transliterates a TypeSafe System One yes probability and optional server confidence. */
+export declare interface SystemOneNoulAnswer {
+    readonly type: 'noul';
+    readonly noul: number;
+    readonly confidence?: number;
+}
+
+/** Transliterates a TypeSafe System One question with its protocol discriminant and criteria. */
+export declare interface SystemOneQuestion {
+    readonly type: 'choice' | 'score' | 'noul';
+    readonly instructions?: SystemOneEntry;
+    readonly criteria?: ChoiceCriteria | ScoreCriteria | NoulCriteria | null;
+}
+
+/** Transliterates the TypeSafe System One request body. */
+export declare interface SystemOneRequest {
+    readonly state: SystemOneEntry;
+    readonly model: string;
+    readonly questions: Readonly<Record<string, SystemOneQuestion>>;
+}
+
+/** Transliterates the System One response envelope before question-specific answer validation. */
+export declare interface SystemOneResponse {
+    readonly model?: string;
+    readonly answers: Readonly<Record<string, unknown>>;
+    readonly usage?: SystemOneUsage;
+}
+
+/** Accepts System One score probabilities and legends as maps or llama.cpp arrays. */
+export declare interface SystemOneScoreAnswer {
+    readonly type: 'score';
+    readonly probabilities: Readonly<Record<string, number>> | readonly number[];
+    readonly score?: number;
+    readonly legend?: Readonly<Record<string, SystemOneEntry>> | readonly SystemOneEntry[];
+    readonly confidence?: number;
+}
+
+/** Transliterates TypeSafe System One token counts with missing or null counts permitted. */
+export declare interface SystemOneUsage {
+    readonly input_tokens?: number | null;
+    readonly output_tokens?: number | null;
+}
+
 /** Carries a decoded stream prefix and whether the stream ended within its byte budget. */
 export declare interface TextRead {
     readonly text: string;