@linxiraos/pi-ai 1.1.15 → 1.1.16

package/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## [Unreleased]
 
-## [1.1.15] - 2026-09-16
+## [1.1.16] - 2026-09-19
 
-- 上游 v18.1.17–v18.1.21 同步:provider 修复与补全回退链强化(保序、预算、同模型区分)随同步带过。
+- 上游 v18.2.5 同步:stencil.so OAuth 认证回调、流式 JSON 代理解析优化。
 

package/README.md

@@ -1084,6 +1084,8 @@ zeta auth-broker logout           # interactive — pick a stored credential to
 
 Credentials are saved to `agent.db` in the agent directory. `/login qianfan` opens the Qianfan console and stores the pasted API key.
 
+If SQLite reports corruption during startup, the damaged database and remaining journal sidecars are preserved beside it as private `agent.db.corrupt-<timestamp>-<id>*` backups before a fresh database is created. The log records the backup path. This restores startup, not unreadable credentials: log in again; retain the backups for manual data recovery. Lock contention and other non-corruption errors never reset the database.
+
 `login` supports OAuth providers (Anthropic, OpenAI Codex, GitHub Copilot, Gemini CLI, Antigravity) and API-key onboarding flows.
 
 For the current API-key onboarding flows, the library covers Together, Moonshot, Qianfan, NVIDIA, NanoGPT, Novita, DeepInfra, Hugging Face, Venice, Xiaomi, vLLM, LiteLLM, Cloudflare AI Gateway, Qwen Portal, and Ollama Cloud. Ollama remains the local runtime integration; set `OLLAMA_API_KEY` only when your local or self-hosted deployment enforces bearer auth.

package/THIRD-PARTY-NOTICES.txt

@@ -10843,7 +10843,7 @@ RUST RUNTIME DEPENDENCY LICENSES
 
 Generated from Cargo.lock by cargo-about 0.8.2 in locked, offline, workspace, all-feature, all-target mode, then restricted using cargo metadata to normal and build edges reachable from the workspace (development-only edges are excluded). cargo-deny independently evaluates the complete all-target graph.
 
-Native Opus (audiopus/audiopus_sys) and PCRE2 (pcre2/pcre2-sys) are covered by the exact crate license payloads below. inferno 0.12.8 is package-scoped as CDDL-1.0: its CDDL-covered source remains available in the locked crates.io source archive at https://crates.io/crates/inferno/0.12.8 and https://github.com/jonhoo/inferno. The full locked license text follows below.
+Native Opus (opus/opusic-sys) and PCRE2 (pcre2/pcre2-sys) are covered by the exact crate license payloads below. inferno 0.12.8 is package-scoped as CDDL-1.0: its CDDL-covered source remains available in the locked crates.io source archive at https://crates.io/crates/inferno/0.12.8 and https://github.com/jonhoo/inferno. The full locked license text follows below.
 
 -------------------------------------------------------------------------------
 License: Apache License 2.0 (Apache-2.0)
@@ -12509,6 +12509,58 @@ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+-------------------------------------------------------------------------------
+License: BSD 3-Clause "New" or "Revised" License (BSD-3-Clause)
+Used by:
+- opusic-sys 0.7.5 (https://github.com/DoumanAsh/opusic-sys)
+
+Full license text:
+
+Copyright 2001-2023 Xiph.Org, Skype Limited, Octasic,
+                    Jean-Marc Valin, Timothy B. Terriberry,
+                    CSIRO, Gregory Maxwell, Mark Borgerding,
+                    Erik de Castro Lopo, Mozilla, Amazon
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+- Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+- Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+- Neither the name of Internet Society, IETF or IETF Trust, nor the
+names of specific contributors, may be used to endorse or promote
+products derived from this software without specific prior written
+permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
+OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Opus is subject to the royalty-free patent licenses which are
+specified at:
+
+Xiph.Org Foundation:
+https://datatracker.ietf.org/ipr/1524/
+
+Microsoft Corporation:
+https://datatracker.ietf.org/ipr/1914/
+
+Broadcom Corporation:
+https://datatracker.ietf.org/ipr/1526/
+
 -------------------------------------------------------------------------------
 License: BSD 3-Clause "New" or "Revised" License (BSD-3-Clause)
 Used by:
@@ -13290,29 +13342,6 @@ jurisdiction of the Federal Courts of the Northern District of
 California and the state courts of the State of California, with
 venue lying in Santa Clara County, California.
 
--------------------------------------------------------------------------------
-License: ISC License (ISC)
-Used by:
-- audiopus_sys 0.2.2 (https://github.com/lakelezz/audiopus_sys.git)
-
-Full license text:
-
-ISC License
-
-Copyright (c) 2019, Lakelezz
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-
 -------------------------------------------------------------------------------
 License: ISC License (ISC)
 Used by:
@@ -18734,7 +18763,7 @@ DEALINGS IN THE SOFTWARE.
 -------------------------------------------------------------------------------
 License: MIT License (MIT)
 Used by:
-- opus 0.3.1 (https://github.com/SpaceManiac/opus-rs)
+- opus 0.4.0 (https://github.com/SpaceManiac/opus-rs)
 
 Full license text:
 

package/dist/types/auth/sqlite-credential-store.d.ts

@@ -4,7 +4,7 @@
  * The public AuthCredentialStore interface remains in ../auth-storage so local
  * and remote stores share the same contract.
  */
-import { Database } from "bun:sqlite";
+import type { Database } from "bun:sqlite";
 import { isSqliteBusyError, isSqliteCorruptionError } from "@linxiraos/pi-utils";
 import type { AuthCredential, AuthCredentialStore, CredentialRefreshLeaseFence, DisabledCredentialSummary, StoredAuthCredential, StoredCredentialBlock } from "../auth-storage.js";
 import type { OAuthCredentials } from "../registry/oauth/types.js";
@@ -29,6 +29,7 @@ export declare function resolveCredentialIdentityKey(provider: string, credentia
 export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
     #private;
     constructor(db: Database);
+    /** Opens credential storage with bounded busy retries and one-shot corruption recovery. */
     static open(dbPath?: string): Promise<SqliteAuthCredentialStore>;
     listAuthCredentials(provider?: string): StoredAuthCredential[];
     listDisabledCredentials(provider?: string): Promise<DisabledCredentialSummary[]>;

package/dist/types/auth-broker/remote-store.d.ts

@@ -51,6 +51,23 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
     get snapshot(): SnapshotResponse;
     /** Re-hydrate the in-memory snapshot from the broker. */
     refreshSnapshot(): Promise<SnapshotResponse>;
+    /**
+     * Stateful probe for broker-side credential changes, mirroring
+     * {@link SqliteAuthCredentialStore.pollExternalChanges} so long-lived broker
+     * clients (notably `auth-gateway serve`) pick up logins/logouts made by
+     * another process without a restart.
+     *
+     * Compares a local content revision, not the broker's numeric generation:
+     * generation is an in-memory counter that resets when the broker process
+     * restarts, so a reconnecting stream can deliver a different credential set
+     * under a repeated (or lower) generation. {@link #refreshCredentialRevision}
+     * bumps the revision whenever the applied credential material actually
+     * changes, catching those cases too. Records foreground activity first: a
+     * low-traffic client's background sync parks after `#backgroundIdleMs`, and
+     * without this wakeup it would never fetch the new snapshot to report in the
+     * first place.
+     */
+    pollExternalChanges(): boolean;
     listAuthCredentials(provider?: string): StoredAuthCredential[];
     /** Broker-backed disabled tombstones; empty against brokers predating the endpoint. */
     listDisabledCredentials(provider?: string, signal?: AbortSignal): Promise<DisabledCredentialSummary[]>;

package/dist/types/auth-gateway/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./http.js";
+export * from "./session-state.js";
 export * from "./server.js";
 export * from "./types.js";

package/dist/types/auth-gateway/session-state.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Server-owned provider session state for the auth-gateway.
+ *
+ * `SimpleStreamOptions.providerSessionState` is how a provider keeps what it
+ * learned about an endpoint across turns of one conversation: Anthropic's
+ * sticky `strictToolsDisabled` / `fastModeDisabled` /
+ * `replayUnsignedThinkingDisabled` flags and dropped-thinking-prefix set,
+ * OpenAI's strict-tools and reasoning-effort fallbacks, Codex's WebSocket and
+ * turn-state sessions. An in-process omp session owns that `Map` for its whole
+ * lifetime, so a grammar-too-large 400 or a fast-mode rejection costs one
+ * wasted round-trip per session rather than one per turn.
+ *
+ * The map is deliberately non-serializable — `Set`/`Map` fields, live sockets,
+ * a `close()` method — so `pi-native-client` strips it from the wire and
+ * `pi-native-server` never accepts it. Gateway clients therefore cannot bring
+ * their own, and without a server-side owner every containerized / robomp turn
+ * re-learns every lesson from a fresh upstream rejection.
+ *
+ * A plain `Map<sessionId, …>` in a long-lived server process is a leak: nothing
+ * ever reclaims an entry, and the entries own timers and sockets. This store is
+ * an LRU with a hard entry ceiling that calls `close()` on everything it drops
+ * and on everything it still holds at shutdown — but it only ever drops an
+ * entry no request is holding, because `close()` on a live entry tears down
+ * state an in-flight stream is still streaming through.
+ */
+import type { Api, Context, Model, ProviderSessionState } from "../types.js";
+/**
+ * Retained logical sessions. Each entry is a handful of small provider records
+ * plus, for Codex, a WebSocket session — cheap to keep, but not free, so the
+ * ceiling is what turns "one entry per session id forever" into a bounded cost.
+ * Eviction is least-recently-used, so the ceiling only ever drops sessions that
+ * have been quiet longer than the 256 most recent ones.
+ */
+export declare const AUTH_GATEWAY_MAX_SESSION_STATES = 256;
+/**
+ * One request's claim on a retained session.
+ *
+ * `release()` is what makes the entry evictable again, so it MUST run for every
+ * outcome of the request — a `finally` at the call site for the synchronous
+ * paths, stream completion for the streaming ones. It is idempotent, so the
+ * two can overlap.
+ */
+export interface AuthGatewaySessionStateLease {
+    /** The map to hand to `streamSimple` as `providerSessionState`. */
+    readonly states: Map<string, ProviderSessionState>;
+    /** Reset account-scoped records if an in-request auth retry switches accounts. */
+    updateAccount(account: string): void;
+    /** Give up this request's claim. Idempotent. */
+    release(): void;
+}
+/** Everything the store needs to place one request on a retained session. */
+export interface AuthGatewaySessionStateRequest {
+    /**
+     * The client's own session key (`prompt_cache_key` / `sessionId`), or
+     * `undefined` when it sent none — blank counts as none. A supplied key is
+     * authoritative: the client is telling us which conversation this is.
+     */
+    clientKey: string | undefined;
+    model: Model<Api>;
+    /**
+     * System prompt, tools and message history of this request. Used only when
+     * `clientKey` is absent, to place the request on the conversation it
+     * continues.
+     */
+    context: Context;
+    /**
+     * Stable identity of the account this request's credential resolved to.
+     * A change means the gateway switched the session to a sibling credential,
+     * so the account-dependent lessons in the retained map are re-probed. The
+     * comparison happens on acquire and whenever an in-request auth retry
+     * resolves a sibling credential.
+     */
+    account: string;
+}
+/**
+ * Bounded per-session provider state, owned by one gateway server instance.
+ *
+ * Two gateways in the same process get separate stores, so neither can hand a
+ * request another gateway's learned state or close it out from under one.
+ *
+ * The recency order is this class's own (a `Map` iterates in insertion order,
+ * and every acquire re-inserts) rather than `LRUCache`'s, because the policy
+ * needs two things a general cache cannot express: an entry that a request is
+ * still holding must be skipped when picking a victim, and an entry must be
+ * able to change key — `LRUCache` disposes on every removal, which is precisely
+ * the `close()` we must not run here.
+ */
+export declare class AuthGatewaySessionStateStore {
+    #private;
+    constructor(max?: number);
+    /** Retained logical sessions. */
+    get size(): number;
+    /**
+     * Claim the provider-session map for one request, created on first use and
+     * returned by reference so provider mutations persist into the next request.
+     *
+     * Keyed by provider + model + conversation (see {@link sessionKeys}). A
+     * client is free to reuse one session id across models, and the coarsest
+     * provider entries do not separate models themselves (`openai-responses`
+     * keys its strict-tools / history-replay record by provider alone,
+     * Antigravity by a single constant), so the model belongs in the key here.
+     * Endpoint is deliberately absent: every provider whose learning is
+     * endpoint-specific already sub-keys it internally
+     * (`anthropic-messages:${baseUrl}\0${modelId}`,
+     * `openai-completions:${provider}:${baseUrl}:${modelId}`), and repeating it
+     * would only fragment the map. The credential is absent for the same reason
+     * — most of what is retained is true of the endpoint whoever calls it, and
+     * Codex already sub-keys its transport by account and bearer — so a
+     * credential switch resets the account-dependent subset instead of
+     * splitting the entry (see `resetAccountScopedProviderSessionState`).
+     *
+     * The returned lease MUST be released; until then the entry cannot be
+     * evicted.
+     */
+    acquire(request: AuthGatewaySessionStateRequest): AuthGatewaySessionStateLease;
+    /** Close and drop every retained state. Called when the gateway shuts down. */
+    close(): void;
+}

package/dist/types/auth-storage.d.ts

@@ -1,5 +1,5 @@
 import type { ApiKeyResolver } from "./auth-retry.js";
-import type { OAuthAuthInfo, OAuthController, OAuthCredentials, OAuthProviderId } from "./registry/oauth/types.js";
+import type { OAuthAuthInfo, OAuthController, OAuthCredentials, OAuthPrompt, OAuthProviderId } from "./registry/oauth/types.js";
 import type { Provider } from "./types.js";
 import type { ClientUsageIdentity, ClientUsageReport, ClientUsageSummary, CredentialRankingStrategy, ObservedUsageEntry, UsageHistoryEntry, UsageHistoryQuery, UsageLogger, UsageProvider, UsageReport } from "./usage.js";
 import { type CodexResetConsumeCode, type CodexResetCredit } from "./usage/openai-codex-reset.js";
@@ -502,6 +502,11 @@ export { isDefinitiveOAuthFailure } from "./error/auth-classify.js";
  * the usage report reveals. Callers that wait the account out (instead of
  * rotating) must sleep until this, not the error-text hint alone.
  *
+ * `requestedBlockedUntilMs` (epoch ms) is this mark call's initial deadline,
+ * before usage-report correction and longest-wins merging. Callers use it to
+ * distinguish the call's replaceable heuristic from a longer merged block
+ * that credential selection will continue enforcing.
+ *
  * `priorBlockedUntilMs` (epoch ms) is the live block deadline the map already
  * stored for this credential before this call. The merged `blockedUntilMs`
  * masks a pre-existing block shorter than this call's own heuristic
@@ -527,6 +532,8 @@ export interface UsageLimitMarkResult {
     switched: boolean;
     retryAtMs?: number;
     blockedUntilMs?: number;
+    /** This mark call's initial deadline, before report correction and merging. */
+    requestedBlockedUntilMs?: number;
     priorBlockedUntilMs?: number;
     priorBlockedUntilTimed?: boolean;
     reportResetAtMs?: number;
@@ -793,7 +800,7 @@ export declare class AuthStorage {
      * Lower priority than {@link setRuntimeApiKey} so a CLI `--api-key`
      * still wins for the duration of a single invocation.
      */
-    setConfigApiKey(provider: string, apiKey: string): void;
+    setConfigApiKey(provider: string, apiKeyConfig: string): void;
     /**
      * Remove a single config-sourced API key override.
      */
@@ -808,6 +815,13 @@ export declare class AuthStorage {
      * Used for custom provider keys from models.json.
      */
     setFallbackResolver(resolver: (provider: string) => string | undefined): void;
+    /**
+     * Install the host's async config-value resolver. Coding-agent uses this so
+     * every stored/config credential reference shares command caching,
+     * failure backoff, and process hardening even when AuthStorage was created
+     * independently and later attached to a registry.
+     */
+    setConfigValueResolver(resolver: (config: string) => Promise<string | undefined>): void;
     /**
      * Reload credentials from storage.
      */
@@ -928,10 +942,7 @@ export declare class AuthStorage {
         /** onAuth is required by auth-storage but optional in OAuthController */
         onAuth: (info: OAuthAuthInfo) => void;
         /** onPrompt is required for some providers (github-copilot, openai-codex) */
-        onPrompt: (prompt: {
-            message: string;
-            placeholder?: string;
-        }) => Promise<string>;
+        onPrompt: (prompt: OAuthPrompt) => Promise<string>;
     }): Promise<OAuthLoginIdentity | undefined>;
     /**
      * Logout from a provider.
@@ -969,6 +980,7 @@ export declare class AuthStorage {
     ingestUsageHeaders(provider: Provider, headers: Record<string, string>, options?: {
         sessionId?: string;
         baseUrl?: string;
+        responseStatus?: number;
     }): boolean;
     /**
      * The {@link UsageProvider} registered for `provider`, or undefined when the
@@ -1116,6 +1128,15 @@ export declare class AuthStorage {
     pinSessionOAuthAccount(provider: string, sessionId: string, credentialId: number, options?: {
         lastUsedAtMs?: number;
     }): boolean;
+    /**
+     * Copy every stored credential affinity from one live session to another.
+     *
+     * The target receives its own sticky entries, so request resolution, usage
+     * blocking, credential rotation, metadata, and persisted pins all continue
+     * through the target session id without retaining a live dependency on the
+     * source session.
+     */
+    inheritSessionCredentials(sourceSessionId: string, targetSessionId: string): number;
     /**
      * Resolve every stored OAuth credential for `provider` independently.
      *

package/dist/types/error/body-error.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Build the classified error for an in-band failure frame, or `undefined` when
+ * the frame is not a retryable in-band failure (in which case the caller keeps
+ * its existing handling and message).
+ *
+ * @param frame decoded SSE `data:` payload, or the `{ error, response }` subset of one
+ */
+export declare function createInBandProviderError(frame: unknown): Error | undefined;
+/**
+ * Build the classified error for a non-JSON SSE frame: gateways and reverse
+ * proxies that answer `data: 429 Too Many Requests` or an HTML throttle page
+ * instead of an OpenAI envelope. `undefined` when the text is not recognisable
+ * as a throttle, so genuinely malformed payloads keep failing loudly.
+ */
+export declare function createInBandProviderErrorFromText(text: string): Error | undefined;

package/dist/types/error/flags.d.ts

@@ -34,6 +34,15 @@ export declare const PYTHON_HTTP2_STREAM_RESET_PATTERN: RegExp;
 export declare const PYTHON_HTTP_INCOMPLETE_CHUNK_PATTERN: RegExp;
 /** reqwest body-frame failures forwarded by the Codex HTTP proxy. */
 export declare const CODEX_HTTP_BODY_READ_ERROR_PATTERN: RegExp;
+/** Exact HTTP request-body-read timeout diagnostic. */
+export declare function isRequestBodyReadTimeout(status: number | undefined, message: string | undefined): boolean;
+/** Exact pre-output Responses 408 that needs a changed-request recovery path. */
+export declare function isResponsesRequestBodyReadTimeout(message: {
+    api?: Api;
+    errorStatus?: number;
+    errorMessage?: string;
+    requestBodyReadTimeoutFullReplay?: boolean;
+}): boolean;
 export declare const TRANSIENT_TRANSPORT_PATTERN: RegExp;
 /**
  * Local llama.cpp / Ollama deterministic tool-call argument JSON parse failure.
@@ -131,6 +140,13 @@ export declare function stringify(id: number | undefined): string;
  * low-signal to trust once detached from a live transport `Error`, which keeps the broad pattern.
  */
 export declare function isTransientStreamParseError(error: unknown): boolean;
+/**
+ * Transport stream-drop diagnostic (see {@link STREAM_DROP_PATTERN}). Unlike
+ * {@link isTransientStreamParseError}, one pattern serves both the live `Error`
+ * and the persisted-string forms: the phrasings are high-signal enough to trust
+ * detached from a transport `Error`.
+ */
+export declare function isTransientStreamDropError(error: unknown): boolean;
 /** Any malformed stream-envelope error (prefix-tagged or out-of-order events). */
 export declare function isStreamEnvelopeError(error: unknown): boolean;
 /** Stream-envelope errors safe to retry against the provider (event ordering only). */

package/dist/types/error/index.d.ts

@@ -2,6 +2,7 @@ export * from "./abort.js";
 export * from "./auth.js";
 export * from "./auth-classify.js";
 export * from "./aws.js";
+export * from "./body-error.js";
 export * from "./classes.js";
 export * from "./finalize.js";
 export * from "./flags.js";

package/dist/types/index.d.ts

@@ -6,8 +6,10 @@ export * from "./auth-gateway/types.js";
 export * from "./auth-retry.js";
 export * from "./auth-storage.js";
 export * from "./error/rate-limit.js";
+export * from "./judgment/index.js";
 export * from "./oneshot-retry.js";
 export * from "./provider-details.js";
+export * from "./provider-session-state.js";
 export * from "./providers/anthropic.js";
 export * from "./providers/anthropic-client.js";
 export * from "./providers/azure-openai-responses.js";

package/dist/types/judgment/chat.d.ts

@@ -0,0 +1,23 @@
+import type { Api, AssistantMessage, Model, SimpleStreamOptions } from "../types.js";
+import type { TextBackend } from "./text.js";
+/**
+ * Output budget for keyword replies. Sized against two independent constraints:
+ *   - Backends that ignore `disableReasoning` still emit a thinking preamble
+ *     (e.g. Qwen3 via llama.cpp catalogued `reasoning: false` but still thinking;
+ *     Anthropic via LiteLLM/Vertex, whose `openai-completions` route downgrades a
+ *     disabled request to the lowest reasoning effort instead of turning thinking
+ *     off). The keyword must have room to land after that preamble (issue #4355).
+ *   - Anthropic-dialect proxies reject `max_tokens <= thinking.budget_tokens`. The
+ *     pinned lowest effort maps to at least Anthropic's 1024-token minimum budget,
+ *     so the cap MUST comfortably exceed 1024 or every call 400s with
+ *     `max_tokens must be greater than thinking.budget_tokens` (issue #8610).
+ * `maxTokens` is a hard cap — non-thinking completions still return in a handful
+ * of tokens.
+ */
+export declare const JUDGMENT_CHAT_MAX_TOKENS = 4096;
+export type ChatTextBackendOptions = Pick<SimpleStreamOptions, "apiKey" | "sessionId" | "metadata"> & {
+    /** Receives every completed attempt (including transient failures) for usage accounting. */
+    onAttempt?: (message: AssistantMessage) => void;
+};
+/** Chat completions with reasoning disabled, temperature 0, and transient-failure retry. */
+export declare function chatTextBackend(model: Model<Api>, options: ChatTextBackendOptions): TextBackend;

package/dist/types/judgment/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./chat.js";
+export * from "./text.js";
+export * from "./types.js";
+export * from "./typesafe.js";

package/dist/types/judgment/text.d.ts

@@ -0,0 +1,59 @@
+import type { Usage } from "../types.js";
+import { type Answer, type Judge, type JudgeOptions, type JudgmentRequest, type JudgmentResult, type JudgmentState, type Question, type Questions } from "./types.js";
+export interface TextPrompt {
+    system: string;
+    user: string;
+    /** Format-correction attempt; chat backends may enforce tool suppression on the wire. */
+    retry?: boolean;
+}
+export interface TextCompletion {
+    text: string;
+    /** Omitted by backends that do not meter tokens (on-device workers). */
+    usage?: Usage;
+}
+/** Completes a rendered judgment prompt; identifies itself for usage attribution. */
+export interface TextBackend {
+    readonly api: string;
+    readonly provider: string;
+    readonly model: string;
+    /** State guard for agent-tuned chat models; on-device classifier workers may disable it. */
+    readonly guardState?: boolean;
+    /** Format-correction retries after a completion cannot be parsed. */
+    readonly parseRetries?: number;
+    complete(prompt: TextPrompt, options: JudgeOptions): Promise<TextCompletion>;
+}
+/** Render judgment state as top-level XML fields; nested values use block YAML. */
+export declare function renderJudgmentState(state: JudgmentState): string;
+/**
+ * Render a request: the system prompt carries the preamble and question
+ * definitions (constant across states, so prompt caches hit); the user message
+ * carries XML-field state followed by the answer-format cue. Small models act
+ * on a bare request (answer it, emit tool calls) instead of classifying it —
+ * explicit tags and the trailing cue keep them on task.
+ */
+export declare function renderJudgmentPrompt(request: JudgmentRequest, options?: {
+    guardState?: boolean;
+}): TextPrompt;
+/**
+ * Earliest option label mentioned in `text`; a longer label wins a tie at the
+ * same position (so `xhigh` beats `high` where both start together).
+ */
+export declare function parseChoiceReply<L extends string>(text: string, labels: readonly L[]): L | undefined;
+/** `true` when a yes-word precedes any no-word, `false` for the reverse, `undefined` when neither appears. */
+export declare function parseNoulReply(text: string): boolean | undefined;
+/** First standalone integer in `[0, levels)`, or `undefined`. */
+export declare function parseScoreReply(text: string, levels: number): number | undefined;
+/**
+ * Split a multi-question reply into `id → answer text`. Lines are matched as
+ * `<id>: <answer>` (also `=` / `-` separators and quoted ids); unknown ids are
+ * ignored so a chatty preamble does not poison parsing.
+ */
+export declare function splitAnswerLines(text: string, ids: readonly string[]): Map<string, string>;
+/** Parse one question's keyword reply into its typed, one-hot answer. */
+export declare function parseAnswer(id: string, question: Question, reply: string): Answer;
+export declare class TextJudge implements Judge {
+    #private;
+    readonly label: string;
+    constructor(backend: TextBackend);
+    judge<Q extends Questions>(request: JudgmentRequest<Q>, options?: JudgeOptions): Promise<JudgmentResult<Q>>;
+}

package/dist/types/judgment/types.d.ts

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