@cleocode/core 2026.9.20 → 2026.9.22

package/dist/decide/jev-wire.js

@@ -0,0 +1,420 @@
+/**
+ * Jev wire adapter — the ONLY module that knows the Jev/"System One" endpoint
+ * paths and wire JSON.
+ *
+ * Maps a provider-neutral {@link DecisionRequest} to a `POST {base}/v1/systemone`
+ * body, maps the response back to a {@link DecisionOutcome}, and validates the
+ * mapped answers with the contract zod schemas. Any service implementing the
+ * Jev wire format (layahost today) is reachable with just a base URL and an
+ * API key.
+ *
+ * Wire notes (from the provider's published OpenAPI document):
+ * - Request: `{ model?, state, questions: { name: { type, instructions, criteria } } }`.
+ *   `model` is sent only when the request names one; the server applies its
+ *   default otherwise. No model identifier is hard-coded here (arch gate 13).
+ * - A `noul` question's wire `criteria` is `{ "true": <description> }`; the
+ *   contract's single criteria string becomes that description, and it also
+ *   serves as the wire `instructions` (the question text) unless the request
+ *   supplies its own instructions.
+ * - Response answers: noul → `{ noul: <P(yes)>, confidence }`; choice →
+ *   `{ choice, probabilities: { option: p }, confidence }`; score →
+ *   `{ score: <expected level>, probabilities: { level: p }, confidence }`.
+ *   Score probabilities are keyed by level text (or, defensively, by 0-based
+ *   index) and re-aligned to the question's `criteria` order.
+ * - Errors: 401, 402 (`insufficient_credits`), 422 (FastAPI validation list),
+ *   429 (with `retry-after`), 5xx. All are thrown as {@link DecisionProviderError}.
+ *
+ * - Model: the provider's OpenAPI marks `SystemOneRequest.model` REQUIRED and
+ *   documents no server-side default for `/v1/systemone` (the `laya-auto`
+ *   default is documented for `/v1/decide` only). The body therefore carries
+ *   `req.model ?? connection.model`; a request with neither is sent without a
+ *   model and the provider may reject it (422 → heuristic fallback).
+ * - `GET /v1/models` → `{ models: [{ name, description?, ... }] }`; used by
+ *   {@link listJevModels} for the reachability probe.
+ *
+ * `/v1/decide` (single question, different body shape) is not used: every
+ * single-question call is a one-question `/v1/systemone` call, so one mapping
+ * covers every request.
+ *
+ * @task T12490
+ * @epic T12486
+ */
+import { decisionAnswerSchema, } from '@cleocode/contracts';
+import { z } from 'zod';
+import { MAX_RATE_LIMIT_COOLDOWN_MS } from './budget.js';
+import { DecisionProviderError, } from './provider.js';
+import { decideFetch } from './transport.js';
+/** Path of the multi-question endpoint, relative to the base URL. */
+const SYSTEMONE_PATH = '/v1/systemone';
+/** Path of the model-listing endpoint, relative to the base URL. */
+const MODELS_PATH = '/v1/models';
+/** Adapter identity + version; part of every cache key so a mapping change invalidates the cache. */
+export const JEV_ADAPTER_VERSION = 'jev-wire/1';
+/** Loose schema for one wire answer; extra fields (e.g. `legend`) are tolerated. */
+const jevAnswerSchema = z.looseObject({
+    type: z.string().optional(),
+    noul: z.number().optional(),
+    choice: z.string().optional(),
+    score: z.number().optional(),
+    confidence: z.number(),
+    probabilities: z.record(z.string(), z.number()).optional(),
+});
+/** Loose schema for the `/v1/systemone` response envelope. */
+const jevResponseSchema = z.looseObject({
+    model: z.string().optional(),
+    answers: z.record(z.string(), jevAnswerSchema),
+    usage: z.looseObject({ input_tokens: z.number().int().nonnegative().optional() }).optional(),
+    meta: z
+        .looseObject({
+        request_id: z.string().optional(),
+        latency_ms: z.number().optional(),
+        cost_usd: z.number().nonnegative().optional(),
+        cached: z.boolean().optional(),
+    })
+        .optional(),
+});
+/**
+ * Map a contract request to the `/v1/systemone` wire body.
+ *
+ * @param req - Provider-neutral request.
+ * @returns The JSON body to POST.
+ */
+export function toJevSystemOneBody(req) {
+    const questions = {};
+    for (const [name, q] of Object.entries(req.questions)) {
+        if (q.type === 'noul') {
+            questions[name] = {
+                type: 'noul',
+                instructions: q.instructions ?? q.criteria,
+                criteria: { true: q.criteria },
+            };
+        }
+        else {
+            questions[name] = { type: q.type, instructions: q.instructions, criteria: q.criteria };
+        }
+    }
+    return {
+        ...(req.model !== undefined ? { model: req.model } : {}),
+        state: req.state,
+        questions,
+    };
+}
+/** Index of the largest value; ties resolve to the lowest index. */
+function argmax(values) {
+    let best = 0;
+    for (let i = 1; i < values.length; i++) {
+        if ((values[i] ?? 0) > (values[best] ?? 0))
+            best = i;
+    }
+    return best;
+}
+function invalid(message) {
+    return new DecisionProviderError('invalid_response', message);
+}
+/** Map one wire answer onto the contract answer for its question. */
+function mapAnswer(name, question, wire) {
+    if (question.type === 'noul') {
+        if (wire.noul === undefined)
+            throw invalid(`answer "${name}" has no noul probability`);
+        return {
+            type: 'noul',
+            value: wire.noul >= 0.5,
+            probability: wire.noul,
+            confidence: wire.confidence,
+        };
+    }
+    if (question.type === 'choice') {
+        const probabilities = wire.probabilities;
+        if (!probabilities)
+            throw invalid(`answer "${name}" has no probabilities`);
+        const options = Object.keys(probabilities);
+        const value = wire.choice !== undefined && wire.choice in probabilities
+            ? wire.choice
+            : options[argmax(options.map((o) => probabilities[o] ?? 0))];
+        if (value === undefined)
+            throw invalid(`answer "${name}" has no choice`);
+        return { type: 'choice', value, probabilities, confidence: wire.confidence };
+    }
+    const probabilities = wire.probabilities;
+    if (!probabilities)
+        throw invalid(`answer "${name}" has no probabilities`);
+    const levels = question.criteria.map((level, index) => {
+        const p = probabilities[level] ?? probabilities[String(index)];
+        if (p === undefined)
+            throw invalid(`answer "${name}" is missing level ${index}`);
+        return p;
+    });
+    return {
+        type: 'score',
+        value: argmax(levels),
+        probabilities: levels,
+        confidence: wire.confidence,
+    };
+}
+/**
+ * Map a `/v1/systemone` response body to a contract outcome.
+ *
+ * Every question in `req` must be answered with the matching type, and every
+ * mapped answer must pass {@link decisionAnswerSchema}; otherwise this throws
+ * `DecisionProviderError('invalid_response')`.
+ *
+ * @param req - The request that was sent (needed to align score levels).
+ * @param body - Parsed JSON response body.
+ * @param latencyMs - Measured wall-clock latency of the call.
+ * @returns The outcome, with `source: 'provider'`.
+ */
+export function fromJevSystemOneResponse(req, body, latencyMs) {
+    const parsed = jevResponseSchema.safeParse(body);
+    if (!parsed.success)
+        throw invalid('response body does not match the systemone shape');
+    const wire = parsed.data;
+    const answers = {};
+    for (const [name, question] of Object.entries(req.questions)) {
+        const wireAnswer = wire.answers[name];
+        if (!wireAnswer)
+            throw invalid(`question "${name}" was not answered`);
+        if (wireAnswer.type !== undefined && wireAnswer.type !== question.type) {
+            throw invalid(`answer "${name}" has type ${wireAnswer.type}, expected ${question.type}`);
+        }
+        const checked = decisionAnswerSchema.safeParse(mapAnswer(name, question, wireAnswer));
+        if (!checked.success)
+            throw invalid(`answer "${name}" failed contract validation`);
+        answers[name] = checked.data;
+    }
+    const requestId = wire.meta?.request_id;
+    const costUsd = wire.meta?.cost_usd;
+    const inputTokens = wire.usage?.input_tokens;
+    return {
+        answers,
+        source: 'provider',
+        latencyMs,
+        ...(requestId ? { requestId } : {}),
+        ...(costUsd !== undefined ? { costUsd } : {}),
+        ...(inputTokens !== undefined ? { inputTokens } : {}),
+    };
+}
+/**
+ * Parse a `retry-after` header (delta seconds or HTTP date) into milliseconds,
+ * capped at {@link MAX_RATE_LIMIT_COOLDOWN_MS}.
+ *
+ * Negative seconds, past dates and anything unparseable are ignored
+ * (`undefined`, so the budget applies its default cool-down). A numeric-looking
+ * value is never re-read as a date: `Date.parse('-5')` is a valid year.
+ *
+ * @param header - Raw header value, or null.
+ * @param now - Current epoch ms (injectable for tests).
+ * @returns Milliseconds to wait (≤ 60 000), or undefined when absent, negative or unparseable.
+ */
+export function parseRetryAfterMs(header, now = Date.now()) {
+    const value = header?.trim();
+    if (!value)
+        return undefined;
+    let ms;
+    if (/^[-+]?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?$/i.test(value)) {
+        ms = Number(value) * 1000;
+    }
+    else {
+        const date = Date.parse(value);
+        if (!Number.isFinite(date))
+            return undefined;
+        ms = date - now;
+    }
+    if (!Number.isFinite(ms) || ms < 0)
+        return undefined;
+    return Math.round(Math.min(ms, MAX_RATE_LIMIT_COOLDOWN_MS));
+}
+/** Classify a non-2xx HTTP status. */
+function errorForStatus(status, retryAfterMs) {
+    const message = `decision provider returned HTTP ${status}`;
+    if (status === 401 || status === 403) {
+        return new DecisionProviderError('unauthorized', message, { status });
+    }
+    if (status === 402)
+        return new DecisionProviderError('insufficient_credits', message, { status });
+    if (status === 429) {
+        return new DecisionProviderError('rate_limited', message, {
+            status,
+            ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+        });
+    }
+    if (status >= 500)
+        return new DecisionProviderError('server_error', message, { status });
+    return new DecisionProviderError('invalid_request', message, { status });
+}
+/** Join a base URL and an absolute endpoint path, tolerating a trailing slash on the base. */
+function endpointUrl(baseUrl, path) {
+    return `${baseUrl.replace(/\/+$/, '')}${path}`;
+}
+/**
+ * Create a {@link DecisionProvider} speaking the Jev wire format.
+ *
+ * @param connection - Base URL + API key. The key is only ever placed in the
+ *   `Authorization` header.
+ * @param opts - Injectable `fetch` and clock.
+ * @returns A provider whose `decide` throws {@link DecisionProviderError} on any failure.
+ *
+ * @example
+ * ```ts
+ * const provider = createJevProvider({ baseUrl: 'https://decide.example', apiKey });
+ * const outcome = await provider.decide(request, AbortSignal.timeout(300));
+ * ```
+ */
+export function createJevProvider(connection, opts = {}) {
+    const doFetch = opts.fetch ?? decideFetch;
+    const now = opts.now ?? (() => performance.now());
+    return {
+        async decide(req, signal) {
+            const started = now();
+            let response;
+            try {
+                response = await doFetch(endpointUrl(connection.baseUrl, SYSTEMONE_PATH), {
+                    method: 'POST',
+                    headers: {
+                        authorization: `Bearer ${connection.apiKey}`,
+                        'content-type': 'application/json',
+                        accept: 'application/json',
+                    },
+                    body: JSON.stringify(toJevSystemOneBody(req.model === undefined && connection.model
+                        ? { ...req, model: connection.model }
+                        : req)),
+                    signal,
+                });
+            }
+            catch (err) {
+                const cause = err instanceof Error ? err : undefined;
+                if (signal.aborted) {
+                    throw new DecisionProviderError('aborted', 'decision request aborted', { cause });
+                }
+                throw new DecisionProviderError('network', 'decision request failed before a response', {
+                    cause,
+                });
+            }
+            if (!response.ok) {
+                // Drain the body so the connection can be reused; its content is not needed.
+                await response.body?.cancel().catch(() => undefined);
+                throw errorForStatus(response.status, parseRetryAfterMs(response.headers.get('retry-after')));
+            }
+            let body;
+            try {
+                body = await response.json();
+            }
+            catch (err) {
+                if (signal.aborted) {
+                    throw new DecisionProviderError('aborted', 'decision request aborted', {
+                        cause: err instanceof Error ? err : undefined,
+                    });
+                }
+                throw invalid('response body is not JSON');
+            }
+            return fromJevSystemOneResponse(req, body, Math.max(0, now() - started));
+        },
+    };
+}
+/**
+ * Allowed shape of a model name: word characters plus `. : / @ -`, 1-128
+ * characters. Anything else (ANSI escapes, control characters, spaces) is
+ * never stored, sent or printed.
+ */
+export const DECISION_MODEL_NAME_PATTERN = /^[\w.:/@-]{1,128}$/;
+/** Byte cap on a `GET /v1/models` response body. */
+export const MAX_MODELS_RESPONSE_BYTES = 256 * 1024;
+/** Cap on the number of model names kept from a listing. */
+export const MAX_MODELS_LISTED = 500;
+/**
+ * Whether `name` is a safe model identifier (see {@link DECISION_MODEL_NAME_PATTERN}).
+ *
+ * @param name - Candidate model name.
+ * @returns True when it may be stored, sent and printed.
+ */
+export function isValidDecisionModelName(name) {
+    return DECISION_MODEL_NAME_PATTERN.test(name);
+}
+/** Loose schema for the `GET /v1/models` response; names are filtered after parsing. */
+const jevModelsSchema = z.looseObject({
+    models: z.array(z.looseObject({ name: z.unknown() })),
+});
+/**
+ * Read a response body as text, failing once it exceeds `maxBytes`.
+ *
+ * @throws {DecisionProviderError} `invalid_response` when the body is too large.
+ */
+async function readBoundedText(response, maxBytes) {
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        await response.body?.cancel().catch(() => undefined);
+        throw invalid('model listing exceeds the size limit');
+    }
+    if (!response.body)
+        return '';
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel().catch(() => undefined);
+            throw invalid('model listing exceeds the size limit');
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+/**
+ * List the models the key may use (`GET {base}/v1/models`).
+ *
+ * The body is capped at {@link MAX_MODELS_RESPONSE_BYTES}; names failing
+ * {@link DECISION_MODEL_NAME_PATTERN} are skipped and at most
+ * {@link MAX_MODELS_LISTED} names are returned.
+ *
+ * @param connection - Base URL + API key (only ever placed in the `Authorization` header).
+ * @param signal - Aborts the request.
+ * @param opts - Injectable `fetch`.
+ * @returns Safe model names in the order the provider lists them.
+ * @throws {DecisionProviderError} On any HTTP, network, abort, size or shape failure.
+ */
+export async function listJevModels(connection, signal, opts = {}) {
+    const doFetch = opts.fetch ?? decideFetch;
+    let response;
+    try {
+        response = await doFetch(endpointUrl(connection.baseUrl, MODELS_PATH), {
+            method: 'GET',
+            headers: { authorization: `Bearer ${connection.apiKey}`, accept: 'application/json' },
+            signal,
+        });
+    }
+    catch (err) {
+        const cause = err instanceof Error ? err : undefined;
+        const kind = signal.aborted ? 'aborted' : 'network';
+        throw new DecisionProviderError(kind, `model listing failed (${kind})`, { cause });
+    }
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => undefined);
+        throw errorForStatus(response.status, parseRetryAfterMs(response.headers.get('retry-after')));
+    }
+    let body;
+    try {
+        body = JSON.parse(await readBoundedText(response, MAX_MODELS_RESPONSE_BYTES));
+    }
+    catch (err) {
+        if (err instanceof DecisionProviderError)
+            throw err;
+        if (signal.aborted)
+            throw new DecisionProviderError('aborted', 'model listing aborted');
+        throw invalid('model listing is not JSON');
+    }
+    const parsed = jevModelsSchema.safeParse(body);
+    if (!parsed.success)
+        throw invalid('model listing does not match the models shape');
+    const names = [];
+    for (const m of parsed.data.models) {
+        if (typeof m.name === 'string' && isValidDecisionModelName(m.name))
+            names.push(m.name);
+        if (names.length >= MAX_MODELS_LISTED)
+            break;
+    }
+    return names;
+}
+//# sourceMappingURL=jev-wire.js.map

package/dist/decide/jev-wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jev-wire.js","sourceRoot":"","sources":["../../src/decide/jev-wire.ts"],"names":[],"mappings":"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"}

package/dist/decide/operations.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Operator-facing decision operations behind `cleo decide config|status|ask`.
+ *
+ * All logic lives here (the CLI handlers are thin, arch gate 6). Every value
+ * these functions return is secret-free: the API key appears only as a masked
+ * last-4 preview.
+ *
+ * @task T12491
+ * @epic T12486
+ */
+import type { DecisionAnswer } from '@cleocode/contracts';
+import { type DecideCredentialsSummary, type SealedDecideConnection } from './credentials.js';
+/** Default deadline for the `GET /v1/models` probe, ms. */
+export declare const DEFAULT_DECIDE_PROBE_TIMEOUT_MS = 3000;
+/** Default deadline for `cleo decide ask`, ms (generous: it is a debug tool). */
+export declare const DEFAULT_DECIDE_ASK_TIMEOUT_MS = 10000;
+/**
+ * Reachability of the configured provider.
+ *
+ * - `reachable`    — `GET /v1/models` answered 2xx.
+ * - `unauthorized` — the provider rejected the key (401/403).
+ * - `unconfigured` — no valid base URL + key stored.
+ * - `unreachable`  — network failure, timeout, or any other HTTP status.
+ */
+export type DecideProviderState = 'reachable' | 'unauthorized' | 'unconfigured' | 'unreachable';
+/** Result of {@link probeDecideProvider}. */
+export interface DecideProbeResult {
+    /** Reachability verdict. */
+    readonly state: DecideProviderState;
+    /** Configured base URL. */
+    readonly baseUrl?: string;
+    /** Masked key preview. */
+    readonly keyPreview?: string;
+    /** Configured default model, when set. */
+    readonly model?: string;
+    /** Whether `GET /v1/models` succeeded (`skipped` when unconfigured). */
+    readonly modelsEndpoint: 'ok' | 'failed' | 'skipped';
+    /** Model names the key may use, when listed. */
+    readonly models?: readonly string[];
+    /** HTTP status of the probe, when one was received. */
+    readonly httpStatus?: number;
+    /** Probe latency, ms. */
+    readonly latencyMs?: number;
+    /** Secret-free explanation or warning. */
+    readonly detail?: string;
+}
+/** Options for {@link probeDecideProvider}. */
+export interface DecideProbeOptions {
+    /** Connection to probe. Default: the stored connection. */
+    readonly connection?: SealedDecideConnection | null;
+    /** `fetch` implementation; tests inject a stub. */
+    readonly fetch?: typeof fetch;
+    /** Deadline, ms. Default {@link DEFAULT_DECIDE_PROBE_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+}
+/**
+ * Probe the provider with `GET {baseUrl}/v1/models` under a short deadline.
+ * Never throws.
+ *
+ * @param opts - Connection, `fetch` and deadline.
+ * @returns The reachability verdict and, when listed, the available models.
+ */
+export declare function probeDecideProvider(opts?: DecideProbeOptions): Promise<DecideProbeResult>;
+/** Input for {@link configureDecide}. */
+export interface DecideConfigureInput {
+    /** Provider base URL. Omitted → the stored URL is kept. */
+    readonly baseUrl?: string;
+    /** API key. Omitted → the stored key is kept. */
+    readonly apiKey?: string;
+    /**
+     * Default model. Omitted → the stored model is kept when the URL is
+     * unchanged; otherwise resolved from the provider's model listing.
+     */
+    readonly model?: string;
+    /** `fetch` for the model lookup; tests inject a stub. */
+    readonly fetch?: typeof fetch;
+    /** Deadline for the model lookup, ms. */
+    readonly timeoutMs?: number;
+}
+/** Result of {@link configureDecide}. */
+export interface DecideConfigureResult extends DecideCredentialsSummary {
+    /** Where the stored model came from. */
+    readonly modelSource: 'flag' | 'stored' | 'provider-listing' | 'none';
+    /** Secret-free warning, e.g. when no model could be resolved. */
+    readonly warning?: string;
+}
+/**
+ * Store the provider settings, merging omitted values with the stored ones.
+ *
+ * The Jev `/v1/systemone` endpoint requires a `model`, and no model literal
+ * may be hard-coded in core (arch gate 13). So when no model is given (and
+ * none is stored for the same URL), this asks the provider (`GET /v1/models`)
+ * and stores the FIRST model it lists — the provider's own ordering; layahost
+ * lists its routing default first. When that lookup fails the settings are
+ * still stored, without a model, and a warning says how to set one.
+ *
+ * @param input - URL, key, optional model.
+ * @returns Secret-free summary plus the model's provenance.
+ * A URL whose host differs from the stored one must come with a fresh key:
+ * the stored key is never re-used (or sent in the model probe) for a new host.
+ *
+ * @throws {DecideCredentialsError} On an invalid URL, blank key, invalid model
+ *   name, or a host change without a fresh key.
+ */
+export declare function configureDecide(input: DecideConfigureInput): Promise<DecideConfigureResult>;
+/**
+ * Remove the stored settings (and rotated backups of them).
+ *
+ * @returns Whether anything was stored, plus the (now empty) summary.
+ */
+export declare function clearDecideConfig(): Promise<DecideCredentialsSummary & {
+    cleared: boolean;
+}>;
+/** Input for {@link askDecideDebug}. */
+export interface DecideAskInput {
+    /** The state to judge. */
+    readonly state: string;
+    /** The yes/no question (becomes the `noul` criteria). */
+    readonly question: string;
+    /** Deadline, ms. Default {@link DEFAULT_DECIDE_ASK_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+    /** Project root for the audit line. Default: the resolved project root. */
+    readonly projectRoot?: string;
+}
+/** Result of {@link askDecideDebug}. */
+export interface DecideAskResult {
+    /** The typed answer. */
+    readonly answer: DecisionAnswer;
+    /** `provider`, `cache` or `fallback`. */
+    readonly source: 'provider' | 'cache' | 'fallback';
+    /** Why the heuristic answered, when it did. */
+    readonly fallbackReason?: string;
+    /** End-to-end latency, ms. */
+    readonly latencyMs: number;
+    /** Provider-reported cost, USD. */
+    readonly costUsd?: number;
+    /** Provider request id. */
+    readonly requestId?: string;
+    /** Configured default model, when set. */
+    readonly model?: string;
+    /** Masked key preview, when configured. */
+    readonly keyPreview?: string;
+}
+/**
+ * Ask one yes/no question through the configured provider (debug surface).
+ * Uses no cache, so a repeat is a real round trip. Never throws.
+ *
+ * @param input - State, question and deadline.
+ * @returns The typed answer with source, fallback reason, latency and cost.
+ */
+export declare function askDecideDebug(input: DecideAskInput): Promise<DecideAskResult>;
+//# sourceMappingURL=operations.d.ts.map

package/dist/decide/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/decide/operations.ts"],"names":[],"mappings":"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"}