@bobobowis/jev-kit 0.0.0-stage → 0.2.0

package/dist/compact/evaluate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * One evaluation of the Level 7 decision from a harness-neutral view of the session: the user
+ * requests so far, the last turn, and context usage when the harness reports it. pi builds the
+ * input from its session; the Claude and Codex hooks build it from the transcript.
+ */
+import type { Decider } from "../events/index.ts";
+import { type CompactAction, type CompactAnswers, type CompactDecision, type CompactState, type Lines, type Usage } from "./should-compact.ts";
+export interface TurnInput {
+    /** Every user request so far, oldest first. */
+    requests: string[];
+    /** The last compaction summary, when there was one. */
+    summary?: string;
+    /** The assistant's last text, empty when the turn was tool calls only. */
+    recentTurn: string;
+    toolsThisTurn: string[];
+    /** Null when the harness gives no reading. */
+    usage: Usage | null;
+    /** Whether there is anything the harness could compact. */
+    compactable: boolean;
+    lines: Lines;
+    turn?: number;
+}
+export interface Evaluation {
+    decision: CompactDecision;
+    message: string | null;
+    usage: Usage | null;
+    answers: CompactAnswers | null;
+    state: CompactState;
+}
+/** The state Jev sees. Built in code from the session, no LLM involved. */
+export declare function buildCompactState(input: TurnInput): CompactState;
+/**
+ * Ask the four questions and decide the tier, reporting a `hook` event either way. The first
+ * request is silent with no call: there is nothing to move on from yet.
+ */
+export declare function evaluateCompaction(input: TurnInput, source: string, decide: Decider, report: (kind: string, payload: Record<string, unknown>) => void, action?: CompactAction): Promise<Evaluation>;

package/dist/compact/evaluate.js

@@ -0,0 +1,31 @@
+import { COMPACT_QUESTIONS, decideTier, tierMessage, } from "./should-compact.js";
+const clip = (s, n) => (s.length > n ? s.slice(0, n - 1) + "…" : s);
+/** The state Jev sees. Built in code from the session, no LLM involved. */
+export function buildCompactState(input) {
+    const previous = [...input.requests.slice(0, -1).map((m) => clip(m, 200)), input.summary ? `Summary so far: ${clip(input.summary, 400)}` : ""].filter(Boolean).join("\n");
+    return {
+        current_request: clip(input.requests.at(-1) ?? "", 600),
+        previous_work: previous || "(nothing before this request)",
+        recent_turn: clip(input.recentTurn.trim() || `(tool calls only: ${input.toolsThisTurn.join(", ") || "none"})`, 600),
+        tools_this_turn: input.toolsThisTurn,
+    };
+}
+/**
+ * Ask the four questions and decide the tier, reporting a `hook` event either way. The first
+ * request is silent with no call: there is nothing to move on from yet.
+ */
+export async function evaluateCompaction(input, source, decide, report, action = "compact_now") {
+    const state = buildCompactState(input);
+    const base = { hook: source, turn: input.turn, usage: input.usage, usage_known: input.usage !== null, lines: input.lines, compactable: input.compactable };
+    if (input.requests.length < 2) {
+        const decision = { tier: "silent", reason: "first request, nothing to move on from" };
+        report("hook", { ...base, tier: decision.tier, reason: decision.reason, message: null, skipped: true });
+        return { decision, message: null, usage: input.usage, answers: null, state };
+    }
+    const { answers } = await decide(source, state, COMPACT_QUESTIONS, { turn: input.turn, context: input.usage, lines: input.lines });
+    const a = answers;
+    const decision = decideTier(a, input.usage, input.compactable, input.lines, state);
+    const message = tierMessage(decision, input.usage, action);
+    report("hook", { ...base, tier: decision.tier, reason: decision.reason, message });
+    return { decision, message, usage: input.usage, answers: a, state };
+}

package/dist/compact/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Compaction: the Level 7 decisions. Four questions after a turn, a tier in code, the verdict for an on-demand tool, and the cut point.
+ */
+export * from "./should-compact.ts";
+export * from "./compact-on-demand.ts";
+export * from "./pick-cut-point.ts";
+export * from "./evaluate.ts";

package/dist/compact/index.js

@@ -0,0 +1,7 @@
+/**
+ * Compaction: the Level 7 decisions. Four questions after a turn, a tier in code, the verdict for an on-demand tool, and the cut point.
+ */
+export * from "./should-compact.js";
+export * from "./compact-on-demand.js";
+export * from "./pick-cut-point.js";
+export * from "./evaluate.js";

package/dist/compact/pick-cut-point.d.ts

@@ -0,0 +1,18 @@
+import type { ChoiceAnswer } from "../core/types.ts";
+export interface TurnSummary {
+    /** Zero based index in the session. */
+    index: number;
+    /** The user message that started the turn, trimmed. */
+    request: string;
+}
+/** One Choice over the turns. Keys are the indices, so the pick is always a real turn. */
+export declare function cutPointQuestion(turns: TurnSummary[]): {
+    live_from: import("../core/types.ts").ChoiceQuestion;
+};
+export interface CutPoint {
+    liveFrom: number | null;
+    confidence: number;
+    instructions: string;
+}
+/** The pick as compaction instructions. Low confidence falls back to pi's default cut. */
+export declare function cutPointInstructions(turns: TurnSummary[], answer: ChoiceAnswer, floor?: number): CutPoint;

package/dist/compact/pick-cut-point.js

@@ -0,0 +1,29 @@
+/**
+ * Level 7, option C: pick the cut point.
+ * When compaction runs, which turn starts the work that is still live? A Choice over the session's turns, each described by the user message that started it. Code turns the pick into the compaction instructions.
+ */
+import { choice } from "../core/helpers.js";
+/** One Choice over the turns. Keys are the indices, so the pick is always a real turn. */
+export function cutPointQuestion(turns) {
+    const criteria = {};
+    for (const t of turns)
+        criteria[String(t.index)] = t.request;
+    criteria.none = "Every turn is still live; keep the most recent context only";
+    return {
+        live_from: choice("Which turn in `turns` starts the work that is still live? Earlier turns can be summarized briefly.", criteria),
+    };
+}
+/** The pick as compaction instructions. Low confidence falls back to pi's default cut. */
+export function cutPointInstructions(turns, answer, floor = 0.6) {
+    if (answer.choice === "none" || answer.confidence < floor) {
+        return { liveFrom: null, confidence: answer.confidence, instructions: "Summarize the earlier work briefly and keep the most recent turns in detail." };
+    }
+    const idx = Number(answer.choice);
+    const turn = turns.find((t) => t.index === idx);
+    const from = turn ? `"${turn.request}"` : `turn ${idx}`;
+    return {
+        liveFrom: idx,
+        confidence: answer.confidence,
+        instructions: `The live work starts at ${from}. Summarize everything before it in a few lines. Keep the decisions, file paths, and open questions from ${from} onward in full detail.`,
+    };
+}

package/dist/compact/should-compact.d.ts

@@ -0,0 +1,57 @@
+import type { NoulAnswer, ScoreAnswer } from "../core/types.ts";
+/** What the hook sends. Built in code from the session, no LLM involved. */
+export type CompactState = {
+    /** The latest user message, trimmed. */
+    current_request: string;
+    /** Earlier user messages plus the last compaction summary, trimmed. */
+    previous_work: string;
+    /** The assistant's last text plus the tools it called, trimmed. */
+    recent_turn: string;
+    tools_this_turn: string[];
+};
+export declare const COMPACT_QUESTIONS: {
+    switched_gears: import("../core/types.ts").NoulQuestion;
+    at_boundary: import("../core/types.ts").NoulQuestion;
+    needs_history: import("../core/types.ts").ScoreQuestion;
+    mid_operation: import("../core/types.ts").NoulQuestion;
+};
+export interface CompactAnswers {
+    switched_gears: NoulAnswer;
+    at_boundary: NoulAnswer;
+    needs_history: ScoreAnswer;
+    mid_operation: NoulAnswer;
+}
+export type Tier = "silent" | "notice" | "recommend" | "request";
+/**
+ * Context tokens, not percent: a 1M window makes percent useless for a short session. Low on
+ * purpose so a few file reads cross them. pi's keepRecentTokens must sit below the notice line.
+ */
+export interface Lines {
+    notice: number;
+    recommend: number;
+    request: number;
+}
+export declare const DEFAULT_LINES: Lines;
+/** What the gauge reads: tokens in context, and the same as a percent of the model's window (null when the window is unknown). */
+export interface Usage {
+    tokens: number;
+    pct: number | null;
+}
+/** A gauge reading in words: "12k tokens, 6.0% of the window", or just the tokens. */
+export declare const usageText: (u: Usage) => string;
+export interface CompactDecision {
+    tier: Tier;
+    reason: string;
+}
+/**
+ * The decision, numbers in code. Silent when there is nothing to compact, when the agent is mid
+ * operation, or when the work has not moved on. Otherwise the tier follows usage against the lines.
+ */
+export declare function decideTier(a: CompactAnswers, usage: Usage | null, compactable: boolean, lines: Lines, state?: CompactState): CompactDecision;
+/**
+ * How the agent can act on a tier: call compact_now itself (pi), or ask the user to run /compact
+ * (Claude Code, Codex, where a tool cannot start compaction).
+ */
+export type CompactAction = "compact_now" | "ask_user";
+/** The exact text the agent sees on its next call. Silent returns null: nothing is injected. */
+export declare function tierMessage(d: CompactDecision, usage: Usage | null, action?: CompactAction): string | null;

package/dist/compact/should-compact.js

@@ -0,0 +1,87 @@
+/**
+ * Level 7, option A: should I compact.
+ * At the end of every agent turn, four questions about the work, one call. The numbers, context usage and the lines, stay in code. Jev judges whether the work moved on. The agent hears nothing, a notice, a recommendation, or a request.
+ */
+import { noul, score } from "../core/helpers.js";
+export const COMPACT_QUESTIONS = {
+    switched_gears: noul("Is `current_request` a different task from `previous_work`?", {
+        true: "A new feature, a different file area, a different goal, or an unrelated question",
+        false: "The same task continuing, a follow up, a fix to what was just done",
+    }),
+    at_boundary: noul("Did `recent_turn` finish a unit of work?", {
+        true: "Tests passed, a commit was made, a summary was given, or a question was asked of the user",
+        false: "Mid task, more steps clearly remain",
+    }),
+    needs_history: score("How much of `previous_work` does the next step need?", [
+        "None; the new work stands alone",
+        "Some references, a file name or a decision",
+        "Most of it; the work continues directly from it",
+    ]),
+    mid_operation: noul("Is the agent in the middle of a multi step edit whose partial state only exists in the conversation?", {
+        true: "Half applied changes, a plan being executed step by step, an unfinished refactor",
+        false: "A clean point, nothing half done",
+    }),
+};
+export const DEFAULT_LINES = { notice: 6000, recommend: 10_000, request: 14_000 };
+/** A gauge reading in words: "12k tokens, 6.0% of the window", or just the tokens. */
+export const usageText = (u) => `${Math.round(u.tokens / 1000)}k tokens${u.pct === null ? "" : `, ${u.pct.toFixed(1)}% of the window`}`;
+const clip = (s, n = 70) => (s.length > n ? s.slice(0, n - 1) + "…" : s);
+/**
+ * The decision, numbers in code. Silent when there is nothing to compact, when the agent is mid
+ * operation, or when the work has not moved on. Otherwise the tier follows usage against the lines.
+ */
+export function decideTier(a, usage, compactable, lines, state) {
+    if (!compactable)
+        return { tier: "silent", reason: "nothing to compact yet" };
+    if (a.mid_operation.noul > 0.6)
+        return { tier: "silent", reason: "mid operation" };
+    const switched = a.switched_gears.noul > 0.7;
+    const boundary = a.at_boundary.noul > 0.6 && a.needs_history.score < 1;
+    if (!switched && !boundary)
+        return { tier: "silent", reason: "same work continuing" };
+    const reason = switched
+        ? `The task changed${state ? ` from "${clip(state.previous_work)}" to "${clip(state.current_request)}"` : ""}.`
+        : "The last turn finished a unit of work and the next step needs little of the earlier context.";
+    // Without a usage reading there are no lines to place it against: the judgment alone earns a notice.
+    if (!usage)
+        return { tier: "notice", reason: `${reason} Context usage is unknown.` };
+    if (usage.tokens < lines.notice)
+        return { tier: "silent", reason: "below the notice line" };
+    if (usage.tokens < lines.recommend)
+        return { tier: "notice", reason };
+    if (usage.tokens < lines.request)
+        return { tier: "recommend", reason };
+    return { tier: "request", reason };
+}
+/** The exact text the agent sees on its next call. Silent returns null: nothing is injected. */
+export function tierMessage(d, usage, action = "compact_now") {
+    if (action === "ask_user")
+        return askUserMessage(d, usage);
+    if (!usage)
+        return d.tier === "silent" ? null : `${d.reason} Compacting is optional. If you do, call compact_now with a short note to yourself.`;
+    const pct = usageText(usage);
+    switch (d.tier) {
+        case "notice":
+            return `Context is at ${pct}. ${d.reason} Compacting is optional. If you do, call compact_now with a short note to yourself.`;
+        case "recommend":
+            return `Recommended: compact now. Context is at ${pct}. ${d.reason} Call compact_now with a short note to yourself, then continue.`;
+        case "request":
+            return `Please compact before continuing. Context is at ${pct}. ${d.reason} Call compact_now with a short note to yourself.`;
+        default:
+            return null;
+    }
+}
+function askUserMessage(d, usage) {
+    const at = usage ? `Context is at ${usageText(usage)}. ` : "";
+    const how = "You cannot compact yourself: ask the user to run /compact, and give them a one line note of what to keep, for example /compact keep the billing fix and its failing test.";
+    switch (d.tier) {
+        case "notice":
+            return `${at}${d.reason} Compacting is optional. At a clean point you may suggest it. ${how}`;
+        case "recommend":
+            return `Recommended: compact soon. ${at}${d.reason} When you reply, suggest it. ${how}`;
+        case "request":
+            return `Please ask the user to compact before continuing. ${at}${d.reason} ${how}`;
+        default:
+            return null;
+    }
+}

package/dist/core/client.d.ts

@@ -0,0 +1,93 @@
+import { type Questions, type State, type SystemOneRequest, type SystemOneResponse } from "./types.ts";
+export type JevProvider = "mock" | "openrouter" | "typesafe";
+/** Caller-supplied USD prices; no assumed provider/model rates. */
+export interface JevPricing {
+    inputPerMillion: number;
+    outputPerMillion: number;
+}
+export type JevCost = {
+    amount: number;
+    source: "reported" | "estimated" | "mock";
+} | {
+    amount: null;
+    source: "unknown";
+};
+export interface JevClientOptions {
+    /** Overrides test isolation, JEV_BACKEND, and automatic key-based selection. */
+    provider?: JevProvider;
+    /** Requires opts.provider to explicitly name a live provider. */
+    apiKey?: string;
+    /** Full endpoint URL (not an origin). Redirects are refused. */
+    baseUrl?: string;
+    /** Pin a versioned model ID instead of the moving alias. */
+    model?: string;
+    /** Total budget including retries and response bodies. Default: 30,000 ms. */
+    timeoutMs?: number;
+    /** Exponential backoff base, plus up to 20% jitter. Default: 500 ms; 0 is allowed. */
+    retryDelayMs?: number;
+    /** Used only when usage.cost is not a valid reported cost. Snapshotted at construction. */
+    pricing?: JevPricing;
+}
+export interface JevRawExchange {
+    /** Snapshot of the JSON sent; no credentials or headers. */
+    request: SystemOneRequest;
+    requestText: string;
+    /** Unenriched provider payload, including unknown fields. */
+    response: SystemOneResponse;
+    /** Exact response body text; mock responses use synthetic JSON. */
+    responseText: string;
+}
+export interface SystemOneResult extends SystemOneResponse {
+    raw: JevRawExchange;
+    meta: {
+        provider: JevProvider;
+        requestedModel: string;
+        resolvedModel: string;
+        elapsedMs: number;
+        attempts: number;
+        /** USD, or null when no trustworthy cost is available. */
+        cost: JevCost;
+    };
+}
+export declare class ContractError extends Error {
+    constructor(message: string);
+}
+/** Live observation of every call — the web layer streams these to the UI. */
+export type JevEvent = {
+    kind: "request";
+    provider: JevProvider;
+    model: string;
+    state: State;
+    questions: Questions;
+} | {
+    kind: "response";
+    result: SystemOneResult;
+};
+export declare class JevClient {
+    readonly provider: JevProvider;
+    private readonly apiKey?;
+    private readonly endpoint?;
+    private readonly mock;
+    private readonly model?;
+    private readonly timeoutMs;
+    private readonly retryDelayMs;
+    private readonly pricing?;
+    private listeners;
+    /** Count of validated systemOne calls, for the demo's cost story. */
+    calls: number;
+    constructor(opts?: JevClientOptions);
+    get isLive(): boolean;
+    /** Observe every request and response this client makes. */
+    on(listener: (event: JevEvent) => void): () => void;
+    private emit;
+    systemOne(state: State, questions: Questions, opts?: {
+        model?: string;
+        signal?: AbortSignal;
+    }): Promise<SystemOneResult>;
+}
+/** Strict live contract; unknown payload fields are deliberately retained. */
+export declare function validateResponse(response: unknown, questions: Questions): asserts response is SystemOneResponse;
+/** Lazily constructed; provider and credentials resolve only on first use. */
+export declare function sharedJev(): JevClient;
+/** Shared client for every level. Use JEV_BACKEND=mock for an offline demo. */
+export declare const jev: JevClient;

package/dist/core/client.js

@@ -0,0 +1,295 @@
+/**
+ * JevClient — a provider and credential snapshot, with no runtime fallback.
+ * Auto-selection prefers TypeSafe, then OpenRouter. Mock requires an explicit
+ * selection or node:test isolation; missing production credentials fail closed.
+ */
+import { MockJev } from "./mock.js";
+import { QuestionValidationError, validateRequest, } from "./types.js";
+const ENDPOINTS = {
+    openrouter: "https://openrouter.ai/api/alpha/decisions",
+    typesafe: "https://api.typesafe.ai/v1/systemone",
+};
+const DEFAULT_MODELS = {
+    openrouter: "~typesafe/jev-latest",
+    typesafe: "jev-latest",
+};
+const KEY_ENV = {
+    openrouter: "OPENROUTER_API_KEY",
+    typesafe: "TYPESAFE_API_KEY",
+};
+const RETRY_STATUSES = new Set([429, 502, 503, 529]);
+const REQUEST_TIMEOUT_MS = 30_000;
+const MAX_ATTEMPTS = 3;
+export class ContractError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ContractError";
+    }
+}
+export class JevClient {
+    provider;
+    apiKey;
+    endpoint;
+    mock = new MockJev();
+    model;
+    timeoutMs;
+    retryDelayMs;
+    pricing;
+    listeners = [];
+    /** Count of validated systemOne calls, for the demo's cost story. */
+    calls = 0;
+    constructor(opts = {}) {
+        if (opts.apiKey !== undefined && opts.provider !== "typesafe" && opts.provider !== "openrouter") {
+            throw new Error("apiKey requires an explicit live opts.provider (typesafe or openrouter).");
+        }
+        this.provider = selectProvider(opts.provider);
+        this.model = opts.model;
+        this.timeoutMs = opts.timeoutMs ?? REQUEST_TIMEOUT_MS;
+        this.retryDelayMs = opts.retryDelayMs ?? 500;
+        if (!Number.isInteger(this.timeoutMs) || this.timeoutMs <= 0 || this.timeoutMs > 2_147_483_647) {
+            throw new Error("timeoutMs must be a positive integer no greater than 2147483647.");
+        }
+        if (!isNonnegative(this.retryDelayMs))
+            throw new Error("retryDelayMs must be finite and nonnegative.");
+        if (opts.pricing !== undefined) {
+            if (!opts.pricing || !isNonnegative(opts.pricing.inputPerMillion) || !isNonnegative(opts.pricing.outputPerMillion)) {
+                throw new Error("pricing requires finite, nonnegative inputPerMillion and outputPerMillion USD rates.");
+            }
+            this.pricing = { ...opts.pricing };
+        }
+        if (this.provider === "mock")
+            return;
+        this.apiKey = (opts.apiKey ?? process.env[KEY_ENV[this.provider]])?.trim();
+        this.endpoint = opts.baseUrl ?? ENDPOINTS[this.provider];
+        if (!this.apiKey) {
+            throw new Error(`Provider "${this.provider}" needs a nonblank apiKey or ${KEY_ENV[this.provider]}.`);
+        }
+    }
+    get isLive() {
+        return this.provider !== "mock";
+    }
+    /** Observe every request and response this client makes. */
+    on(listener) {
+        this.listeners.push(listener);
+        return () => {
+            this.listeners = this.listeners.filter((l) => l !== listener);
+        };
+    }
+    emit(event) {
+        for (const listener of this.listeners)
+            listener(event);
+    }
+    async systemOne(state, questions, opts = {}) {
+        opts.signal?.throwIfAborted();
+        const requestedModel = opts.model ?? this.model ??
+            (this.provider === "mock" ? this.mock.model : DEFAULT_MODELS[this.provider]);
+        const body = { model: requestedModel, state, questions };
+        validateRequest(body);
+        let requestText;
+        try {
+            requestText = JSON.stringify(body);
+        }
+        catch {
+            throw new QuestionValidationError("Request must be JSON-serializable (no cycles or BigInt).");
+        }
+        const request = JSON.parse(requestText);
+        // Validate the actual wire snapshot too (e.g. user-defined toJSON methods).
+        validateRequest(request);
+        this.calls++;
+        const started = performance.now();
+        this.emit({ kind: "request", provider: this.provider, model: requestedModel, state, questions });
+        if (this.provider === "mock") {
+            opts.signal?.throwIfAborted();
+            const response = this.mock.systemOne(request);
+            const raw = { request, requestText, response, responseText: JSON.stringify(response) };
+            const out = withMeta(raw, this.provider, requestedModel, started, 1, this.pricing);
+            this.emit({ kind: "response", result: out });
+            return out;
+        }
+        const deadline = new AbortController();
+        const timer = setTimeout(() => {
+            deadline.abort(new DOMException("Jev request timed out.", "TimeoutError"));
+        }, this.timeoutMs);
+        const signal = opts.signal ? AbortSignal.any([deadline.signal, opts.signal]) : deadline.signal;
+        try {
+            for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+                signal.throwIfAborted();
+                const res = await fetch(this.endpoint, {
+                    method: "POST",
+                    headers: { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" },
+                    body: requestText,
+                    signal,
+                    redirect: "error",
+                });
+                signal.throwIfAborted();
+                if (RETRY_STATUSES.has(res.status) && attempt < MAX_ATTEMPTS) {
+                    const backoff = this.retryDelayMs * 2 ** (attempt - 1) * (1 + Math.random() * 0.2);
+                    const delay = Math.min(8000, Math.max(backoff, retryAfterMs(res.headers.get("retry-after"))));
+                    await res.body?.cancel();
+                    await sleep(delay, signal);
+                    continue;
+                }
+                if (!res.ok) {
+                    await res.body?.cancel();
+                    const hint = res.status === 401 ? ` Check the ${KEY_ENV[this.provider]} key.`
+                        : res.status === 402 ? " Check account credits." : "";
+                    throw new Error(`${this.provider} HTTP ${res.status}.${hint}`);
+                }
+                const responseText = await res.text();
+                signal.throwIfAborted();
+                let response;
+                try {
+                    response = JSON.parse(responseText);
+                }
+                catch {
+                    throw new ContractError("Invalid response JSON.");
+                }
+                validateResponse(response, request.questions);
+                const raw = { request, requestText, response, responseText };
+                const out = withMeta(raw, this.provider, requestedModel, started, attempt, this.pricing);
+                this.emit({ kind: "response", result: out });
+                return out;
+            }
+            throw new Error(`${this.provider} retries exhausted`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+function selectProvider(explicit) {
+    // node:test cannot accidentally use ambient live credentials/overrides.
+    // Explicit opts.provider or the existing JEV_LIVE=1 opt-in bypass isolation.
+    const isolated = process.env.NODE_TEST_CONTEXT && process.env.JEV_LIVE !== "1";
+    const selected = explicit ?? (isolated ? "mock" : process.env.JEV_BACKEND?.trim() || undefined);
+    if (selected !== undefined) {
+        if (selected === "mock" || selected === "typesafe" || selected === "openrouter")
+            return selected;
+        throw new Error(`Unknown JEV backend "${selected}"; use mock, openrouter, or typesafe.`);
+    }
+    if (process.env.TYPESAFE_API_KEY?.trim())
+        return "typesafe";
+    if (process.env.OPENROUTER_API_KEY?.trim())
+        return "openrouter";
+    throw new Error("No Jev credentials: set TYPESAFE_API_KEY or OPENROUTER_API_KEY, or explicitly select provider: mock / JEV_BACKEND=mock for offline use.");
+}
+function resultCost(response, provider, pricing) {
+    if (provider === "mock")
+        return { amount: 0, source: "mock" };
+    if (isNonnegative(response.usage.cost))
+        return { amount: response.usage.cost, source: "reported" };
+    if (pricing) {
+        const amount = response.usage.input_tokens / 1_000_000 * pricing.inputPerMillion +
+            response.usage.output_tokens / 1_000_000 * pricing.outputPerMillion;
+        if (isNonnegative(amount))
+            return { amount, source: "estimated" };
+    }
+    return { amount: null, source: "unknown" };
+}
+function withMeta(raw, provider, requestedModel, started, attempts, pricing) {
+    return {
+        // Separate nested answers/usage from raw; enrichment never edits provider data.
+        ...structuredClone(raw.response),
+        raw,
+        meta: {
+            provider,
+            requestedModel,
+            resolvedModel: raw.response.model,
+            elapsedMs: Math.round(performance.now() - started),
+            attempts,
+            cost: resultCost(raw.response, provider, pricing),
+        },
+    };
+}
+/** Ignore malformed/negative values instead of letting NaN erase the backoff. */
+function retryAfterMs(header) {
+    if (!header?.trim())
+        return 0;
+    const value = header.trim();
+    if (/^\d+(?:\.\d+)?$/.test(value)) {
+        const ms = Number(value) * 1000;
+        return Number.isFinite(ms) ? ms : 0;
+    }
+    // HTTP-date forms begin with a weekday; Date.parse alone also accepts "-1".
+    if (!/^(Mon|Tue|Wed|Thu|Fri|Sat|Sun)/i.test(value))
+        return 0;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : 0;
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        signal.throwIfAborted();
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", onAbort);
+            reject(signal.reason);
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+const isObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+const isNonnegative = (x) => typeof x === "number" && Number.isFinite(x) && x >= 0;
+const isUnit = (x) => isNonnegative(x) && x <= 1;
+const isTokenCount = (x) => isNonnegative(x) && Number.isSafeInteger(x);
+/** Strict live contract; unknown payload fields are deliberately retained. */
+export function validateResponse(response, questions) {
+    if (!isObject(response) || !isObject(response.answers) || typeof response.model !== "string" || !response.model.trim()) {
+        throw new ContractError("Invalid response envelope: expected model and answers.");
+    }
+    if (!isObject(response.usage) || !isTokenCount(response.usage.input_tokens) || !isTokenCount(response.usage.output_tokens)) {
+        throw new ContractError("Invalid response usage: expected nonnegative integer input_tokens and output_tokens.");
+    }
+    for (const [id, q] of Object.entries(questions)) {
+        const answer = response.answers[id];
+        if (!Object.hasOwn(response.answers, id) || !isObject(answer) || answer.type !== q.type) {
+            throw new ContractError(`Missing or mismatched answer: ${id}`);
+        }
+        if (q.type === "noul") {
+            if (!isUnit(answer.noul))
+                throw new ContractError(`Invalid noul: ${id}`);
+            continue;
+        }
+        if (!isUnit(answer.confidence) || !isObject(answer.probabilities)) {
+            throw new ContractError(`Invalid distribution: ${id}`);
+        }
+        const keys = q.type === "choice" ? Object.keys(q.criteria) : q.criteria.map((_, i) => String(i));
+        const probs = answer.probabilities;
+        if (Object.keys(probs).length !== keys.length || !keys.every((k) => Object.hasOwn(probs, k) && isUnit(probs[k]))) {
+            throw new ContractError(`Distribution keys must match the declared criteria: ${id}`);
+        }
+        const sum = keys.reduce((acc, k) => acc + probs[k], 0);
+        if (Math.abs(sum - 1) > 0.025)
+            throw new ContractError(`Distribution does not sum to one: ${id} (${sum})`);
+        if (q.type === "choice" && (typeof answer.choice !== "string" || !keys.includes(answer.choice))) {
+            throw new ContractError(`Undeclared choice returned: ${id}`);
+        }
+        if (q.type === "score") {
+            if (!isNonnegative(answer.score) || answer.score > keys.length - 1) {
+                throw new ContractError(`Score out of range: ${id}`);
+            }
+            const legend = answer.legend;
+            if (!isObject(legend) || Object.keys(legend).length !== keys.length ||
+                !keys.every((k, i) => Object.hasOwn(legend, k) && legend[k] === q.criteria[i])) {
+                throw new ContractError(`Score legend must match the declared criteria: ${id}`);
+            }
+        }
+    }
+}
+let _shared;
+/** Lazily constructed; provider and credentials resolve only on first use. */
+export function sharedJev() {
+    if (!_shared)
+        _shared = new JevClient();
+    return _shared;
+}
+/** Shared client for every level. Use JEV_BACKEND=mock for an offline demo. */
+export const jev = new Proxy({}, {
+    get(_target, prop) {
+        const value = sharedJev()[prop];
+        return typeof value === "function" ? value.bind(sharedJev()) : value;
+    },
+});