@sema-agent/client-core 0.98.0 → 0.100.0

package/dist/memoryEntriesWire.js

@@ -1,3 +1,4 @@
+import { readThrownSlot, THROWN_SLOT_UNREADABLE } from './wireFailureShape.js';
 function nonEmptyString(v) {
     return typeof v === 'string' && v !== '';
 }
@@ -216,16 +217,10 @@ export function readMemoryEraseReceipt(body) {
             return { kind: 'malformed', why: 'body_unreadable' };
         o = body;
         envelopeSeen = ['v', 'requestId', 'status', 'erased', 'notFound'].some((k) => Object.hasOwn(o, k));
-        rawV = Object.hasOwn(o, 'v') ? o.v : undefined;
-        rawRequestId = o.requestId;
-        rawStatus = o.status;
-        rawEvidence = o.evidenceCapability;
-        rawCustody = o.custodyState;
-        rawSelected = o.resolvedIds;
-        rawErased = o.erased;
-        rawNotFound = o.notFound;
-        rawPreviously = Object.hasOwn(o, 'erasedPreviously') ? o.erasedPreviously : undefined;
-        rawConflicts = o.conflicts;
+        const slots = ['v', 'requestId', 'status', 'evidenceCapability', 'custodyState', 'resolvedIds', 'erased', 'notFound', 'erasedPreviously', 'conflicts'].map((k) => readThrownSlot(o, k, 'data'));
+        if (slots.includes(THROWN_SLOT_UNREADABLE))
+            return { kind: 'malformed', why: 'body_unreadable' };
+        [rawV, rawRequestId, rawStatus, rawEvidence, rawCustody, rawSelected, rawErased, rawNotFound, rawPreviously, rawConflicts] = slots;
     }
     catch {
         return { kind: 'malformed', why: 'body_unreadable' };

package/dist/model/onboardJudgement.d.ts

@@ -0,0 +1,93 @@
+import type { ModelApiWord } from './providerPresets.js';
+import type { OnboardCatalogIssue, OnboardProbeResult, OnboardProbeVerdict, OnboardRefusal } from '../seatContract.js';
+import { type ModelProbeResult } from '../modelCapabilityProbe.js';
+import type { UiLanguage } from '../env/uiLanguage.js';
+export declare function onboardBaseUrlProblem(url: string, lang?: UiLanguage): string | undefined;
+export interface OnboardProbeTarget {
+    readonly baseUrl: string;
+    readonly api: ModelApiWord;
+    readonly modelId?: string | undefined;
+    readonly apiKey?: string | undefined;
+    readonly auth?: 'bearer' | 'x-api-key' | undefined;
+}
+export interface OnboardProbeRequestInit {
+    method?: string;
+    headers: Record<string, string>;
+    body?: string;
+    redirect: 'manual';
+    signal: AbortSignal;
+}
+export interface OnboardProbeBodyReader {
+    read(): Promise<{
+        readonly done: boolean;
+        readonly value?: Uint8Array | undefined;
+    }>;
+    cancel(): Promise<void>;
+}
+export interface OnboardProbeResponse {
+    readonly status: number;
+    readonly ok: boolean;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    readonly body?: {
+        getReader(): OnboardProbeBodyReader;
+    } | null | undefined;
+    text(): Promise<string>;
+}
+export type OnboardProbeFetch = (url: string, init: OnboardProbeRequestInit) => Promise<OnboardProbeResponse>;
+export interface OnboardProbeDeps {
+    readonly fetchImpl?: OnboardProbeFetch | undefined;
+    readonly timeoutMs?: number | undefined;
+    readonly firstTokenMs?: number | undefined;
+}
+export declare function probeModelEndpoint(target: OnboardProbeTarget, deps?: OnboardProbeDeps): Promise<OnboardProbeResult>;
+export type OnboardWriteVerdict = {
+    readonly write: true;
+    readonly unverified: boolean;
+} | {
+    readonly write: false;
+    readonly refusal: 'probe_failed' | 'probe_unverified';
+};
+export declare function onboardWriteVerdict(verdict: OnboardProbeVerdict, acceptUnverified?: boolean): OnboardWriteVerdict;
+export declare function keyEnvNameForEntry(entryName: string): string;
+export declare function poolEntryNameOf(modelId: string, channel: string, taken: ReadonlySet<string>): string;
+export interface OnboardPlanEntry {
+    readonly modelId: string;
+    readonly api: ModelApiWord;
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly providerName: string;
+    readonly contextWindow: number;
+    readonly maxTokens: number;
+    readonly channel: string;
+}
+export interface OnboardJsonObject {
+    readonly [key: string]: {} | null;
+}
+export interface OnboardWritePlanInput {
+    readonly modelsDoc: OnboardJsonObject | undefined;
+    readonly settingsEnv: OnboardJsonObject | undefined;
+    readonly effectiveEnv: Readonly<Record<string, string | undefined>>;
+    readonly entry: OnboardPlanEntry;
+    readonly probe: OnboardProbeResult;
+    readonly makeDefault: boolean;
+    readonly now: number;
+    readonly thinking?: ModelProbeResult | undefined;
+    readonly engineMode?: 'local' | 'cloud' | undefined;
+}
+export type OnboardWritePlan = {
+    readonly ok: true;
+    readonly entryName: string;
+    readonly keyEnv: string;
+    readonly updatedExisting: boolean;
+    readonly nextModelsDoc: OnboardJsonObject;
+    readonly nextSettingsEnv: OnboardJsonObject;
+    readonly otherIssues: readonly OnboardCatalogIssue[];
+} | {
+    readonly ok: false;
+    readonly refusal: Extract<OnboardRefusal, 'input' | 'catalog_unreadable' | 'credential_unpaired' | 'engine_is_remote' | 'env_catalog_present'>;
+    readonly detail: string;
+};
+export declare function onboardWritePlan(input: OnboardWritePlanInput): OnboardWritePlan;
+export declare function onboardRefusalText(refusal: OnboardRefusal, lang?: UiLanguage): string;

package/dist/model/onboardJudgement.js

@@ -0,0 +1,415 @@
+import { ONBOARD_REFUSALS } from '../seatContract.js';
+import { joinRequestUrl, routeKeyOf } from '../coreValuePorts.js';
+import { applyProbeToEntry, probeModelLiveness, probeVerdictNotice } from '../modelCapabilityProbe.js';
+import { ownDataField } from '../ownKey.js';
+import { msg, renderMessage } from '../i18n/translate.js';
+const field = (v, key) => {
+    if (v === null || typeof v !== 'object')
+        return undefined;
+    try {
+        return ownDataField(v, key);
+    }
+    catch {
+        return undefined;
+    }
+};
+const en = (key, params) => renderMessage(msg(key, params));
+function decodeLenient(t) {
+    let cur = t;
+    for (let i = 0; i < 16; i++) {
+        const next = cur.replace(/(?:%[0-9A-Fa-f]{2})+/g, (m) => {
+            try {
+                return decodeURIComponent(m);
+            }
+            catch {
+                return m.replace(/%([0-9A-Fa-f]{2})/g, (_x, h) => String.fromCharCode(parseInt(h, 16)));
+            }
+        });
+        if (next === cur)
+            return cur;
+        cur = next;
+    }
+    return undefined;
+}
+function decodeDeep(t) {
+    let cur = t;
+    for (let i = 0; i < 16; i++) {
+        if (!cur.includes('%'))
+            return cur;
+        let next;
+        try {
+            next = decodeURIComponent(cur);
+        }
+        catch {
+            return undefined;
+        }
+        if (next === cur)
+            return cur;
+        cur = next;
+    }
+    return undefined;
+}
+function safeDecode(t) {
+    try {
+        return decodeURIComponent(t);
+    }
+    catch {
+        return t;
+    }
+}
+function carriesKey(text, key) {
+    if (key === undefined || key === '')
+        return false;
+    const d = decodeDeep(text);
+    if (d === undefined)
+        return true;
+    const k = key.toLowerCase();
+    return text.toLowerCase().includes(k) || d.toLowerCase().includes(k);
+}
+function looksLikeSecret(val) {
+    return /^(sk|ak|pk|rk)[-_]/i.test(val) || (val.length >= 20 && /[A-Za-z]/.test(val) && /[0-9]/.test(val) && /^[A-Za-z0-9._~+/=-]+$/.test(val));
+}
+function redact(text, key) {
+    if (key === undefined || key === '')
+        return text;
+    const out = text.split(key).join('****');
+    const k = key.toLowerCase();
+    const d = decodeLenient(out);
+    return d === undefined || out.toLowerCase().includes(k) || d.toLowerCase().includes(k) ? en('onboard.probe.keyEchoed') : out;
+}
+const capText = (text) => (text.length > 400 ? `${text.slice(0, 400)}…` : text);
+export function onboardBaseUrlProblem(url, lang) {
+    const say = (key) => renderMessage(msg(key), lang);
+    if (typeof url !== 'string')
+        return say('onboard.baseUrl.invalid');
+    if (/\s/.test(url.trim()))
+        return say('onboard.baseUrl.spaces');
+    let u;
+    try {
+        u = new URL(url.trim());
+    }
+    catch {
+        return say('onboard.baseUrl.invalid');
+    }
+    if (u.protocol !== 'http:' && u.protocol !== 'https:')
+        return say('onboard.baseUrl.scheme');
+    if (u.username !== '' || u.password !== '')
+        return say('onboard.baseUrl.userinfo');
+    if (u.hash !== '')
+        return say('onboard.baseUrl.fragment');
+    if (u.pathname.split('/').some((seg) => /^(sk|ak|pk|rk)[-_]/i.test(safeDecode(seg))))
+        return say('onboard.baseUrl.pathKey');
+    for (const [k, val] of u.searchParams) {
+        if (/key|token|secret|auth|sig|pass/i.test(k))
+            return say('onboard.baseUrl.queryKey');
+        if (looksLikeSecret(val))
+            return say('onboard.baseUrl.queryValueKey');
+    }
+    if (decodeDeep(url.trim()) === undefined)
+        return say('onboard.baseUrl.encoding');
+    return undefined;
+}
+function keyHeaders(api, key, auth) {
+    const h = {};
+    if (key !== undefined && key !== '') {
+        if (auth !== 'x-api-key' || api !== 'anthropic-messages')
+            h['authorization'] = `Bearer ${key}`;
+        if (api === 'anthropic-messages' && auth !== 'bearer')
+            h['x-api-key'] = key;
+    }
+    return h;
+}
+class OnboardRedirect extends Error {
+}
+function redirectRefusal(res, url, key) {
+    if (res.status < 300 || res.status >= 400)
+        return undefined;
+    let where = en('onboard.probe.anotherAddress');
+    try {
+        const to = res.headers.get('location');
+        if (to)
+            where = redact(to, key) === to ? new URL(to, url).host : en('onboard.probe.anotherAddress');
+    }
+    catch {
+        where = en('onboard.probe.anotherAddress');
+    }
+    return en('onboard.probe.redirected', { status: res.status, where });
+}
+function probeDetailOf(v) {
+    if (v.verdict === 'ok' && v.waitedMs === undefined && v.path !== undefined && v.httpStatus !== undefined) {
+        return en('onboard.probe.endpointReachable', { method: v.path === '/models' ? 'GET' : 'POST', path: v.path, status: v.httpStatus });
+    }
+    const line = probeVerdictNotice(v).line;
+    const tail = v.apiError ?? v.cause;
+    const detail = tail === undefined ? line : `${line}: ${tail}`;
+    return v.nearModelId === undefined ? detail : en('onboard.probe.modelSuggest', { error: detail, near: v.nearModelId });
+}
+export async function probeModelEndpoint(target, deps) {
+    const apiKey = field(target, 'apiKey');
+    const key = typeof apiKey === 'string' ? apiKey : undefined;
+    const redactKey = key?.trim() || undefined;
+    const out = (verdict, detail) => Object.freeze({ verdict, detail: capText(redact(detail, redactKey)) });
+    const baseUrl = field(target, 'baseUrl');
+    const api = field(target, 'api');
+    const rawModel = field(target, 'modelId');
+    const modelId = typeof rawModel === 'string' && rawModel.trim() !== '' ? rawModel.trim() : undefined;
+    const auth = field(target, 'auth');
+    if (typeof baseUrl !== 'string' || (api !== 'anthropic-messages' && api !== 'openai-completions'))
+        return out('other', en('onboard.probe.incomplete'));
+    const f = (field(deps, 'fetchImpl') ?? globalThis.fetch);
+    if (typeof f !== 'function')
+        return out('unreachable', en('onboard.probe.noFetch'));
+    const num = (k) => {
+        const v = field(deps, k);
+        return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : undefined;
+    };
+    const timeoutMs = num('timeoutMs');
+    const deadlineMs = num('firstTokenMs') ?? timeoutMs ?? 15_000;
+    const root = baseUrl.trim();
+    try {
+        if (joinRequestUrl(root, 'models') === undefined)
+            return out('other', en('onboard.probe.judgeAbsent'));
+    }
+    catch {
+        return out('other', en('onboard.baseUrl.invalid'));
+    }
+    const secret = keyHeaders(api, key, auth === 'bearer' || auth === 'x-api-key' ? auth : undefined);
+    const seen = {};
+    const fetchWithKey = async (url, init) => {
+        const res = await f(url, { method: init.method, headers: { ...init.headers, ...secret }, ...(init.body !== undefined ? { body: init.body } : {}), redirect: 'manual', signal: init.signal });
+        const refusal = redirectRefusal(res, url, redactKey);
+        if (refusal !== undefined) {
+            if (init.method === 'POST' || api === 'openai-completions')
+                seen.redirected = refusal;
+            throw new OnboardRedirect(refusal);
+        }
+        return { status: res.status, headers: res.headers, body: res.body ?? null, text: () => res.text() };
+    };
+    const v = await probeModelLiveness({
+        api,
+        baseUrl: root,
+        ...(modelId !== undefined ? { modelId } : {}),
+        fetch: fetchWithKey,
+        firstTokenBudgetMs: deadlineMs,
+        catalogBudgetMs: timeoutMs ?? (api === 'anthropic-messages' ? 8000 : 10_000),
+        requestUrl: (path) => joinRequestUrl(root, path),
+        redact: (text) => redact(text, redactKey),
+    });
+    if (v.verdict === 'unreachable' && seen.redirected !== undefined)
+        return out('unreachable', seen.redirected);
+    return out(v.verdict, probeDetailOf(v));
+}
+export function onboardWriteVerdict(verdict, acceptUnverified) {
+    if (verdict === 'ok')
+        return Object.freeze({ write: true, unverified: false });
+    if (verdict === 'auth' || verdict === 'model' || verdict === 'shape')
+        return Object.freeze({ write: false, refusal: 'probe_failed' });
+    return acceptUnverified === true ? Object.freeze({ write: true, unverified: true }) : Object.freeze({ write: false, refusal: 'probe_unverified' });
+}
+const KEY_SLOT_PREFIX = 'SEMA_MODEL_KEY_';
+export function keyEnvNameForEntry(entryName) {
+    const base = String(entryName).toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'ENTRY';
+    return `${KEY_SLOT_PREFIX}${base}`;
+}
+export function poolEntryNameOf(modelId, channel, taken) {
+    let name = String(modelId).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[._-]+/, '');
+    if (!name)
+        name = 'model';
+    if (name === 'default')
+        name = 'm-default';
+    let candidate = name;
+    if (taken.has(candidate))
+        candidate = `${name}-${channel}`;
+    for (let i = 2; taken.has(candidate); i++)
+        candidate = `${name}-${channel}-${i}`;
+    return candidate;
+}
+function entryCredentialIssue(m, env) {
+    const name = typeof m['name'] === 'string' ? m['name'] : '?';
+    if (m['sealedApiKey'] !== undefined && m['sealedApiKey'] !== null)
+        return undefined;
+    const keyEnv = typeof m['apiKeyEnv'] === 'string' && m['apiKeyEnv'] !== '' ? m['apiKeyEnv'] : undefined;
+    if (keyEnv !== undefined) {
+        const v = env[keyEnv];
+        return typeof v === 'string' && v.length > 0 ? undefined : en('onboard.catalog.keyEnvUnset', { name, keyEnv });
+    }
+    const base = typeof m['baseUrl'] === 'string' ? m['baseUrl'] : '';
+    if (base.trim() === '')
+        return undefined;
+    const api = typeof m['api'] === 'string' ? m['api'] : 'openai-completions';
+    const rootKey = api === 'anthropic-messages' ? 'ANTHROPIC_BASE_URL' : 'MODEL_GATEWAY_BASEURL';
+    const root = env[rootKey];
+    let paired;
+    try {
+        const a = routeKeyOf(base);
+        if (a === undefined)
+            return en('onboard.catalog.judgeAbsent', { name });
+        paired = typeof root === 'string' && root !== '' && a === routeKeyOf(root);
+    }
+    catch {
+        paired = false;
+    }
+    if (paired)
+        return undefined;
+    const hostOf = (u) => {
+        try {
+            return new URL(u).host;
+        }
+        catch {
+            return en('onboard.catalog.unparseableHost');
+        }
+    };
+    const rootText = typeof root === 'string' && root !== '' ? `${rootKey} (${hostOf(root)})` : en('onboard.catalog.noRoot', { rootKey });
+    return en('onboard.catalog.unpaired', { name, host: hostOf(base), root: rootText });
+}
+function migrateLegacyDefaultKey(doc) {
+    const legacy = doc['default'];
+    if (typeof legacy !== 'string' || legacy.length === 0)
+        return doc;
+    const { default: _legacy, ...rest } = doc;
+    void _legacy;
+    const prevRoles = rest['roles'];
+    const roles = prevRoles !== null && typeof prevRoles === 'object' && !Array.isArray(prevRoles) ? { ...prevRoles } : {};
+    roles['default'] = { model: legacy };
+    return { ...rest, roles };
+}
+export function onboardWritePlan(input) {
+    const rawKey = field(field(input, 'entry'), 'apiKey');
+    const planKey = typeof rawKey === 'string' && rawKey !== '' ? rawKey : undefined;
+    const say = (text) => redact(text, planKey);
+    const refuse = (refusal, detail) => Object.freeze({ ok: false, refusal, detail: say(detail) });
+    try {
+        if (input.engineMode === 'cloud')
+            return refuse('engine_is_remote', en('onboard.refusal.engineIsRemote'));
+        const rawDoc = input.modelsDoc;
+        if (rawDoc !== undefined && (rawDoc === null || typeof rawDoc !== 'object' || Array.isArray(rawDoc)))
+            return refuse('catalog_unreadable', en('onboard.plan.notObject'));
+        const doc = migrateLegacyDefaultKey(rawDoc === undefined ? {} : { ...rawDoc });
+        const rawModels = doc['models'];
+        if (rawModels !== undefined && !Array.isArray(rawModels))
+            return refuse('catalog_unreadable', en('onboard.plan.modelsNotList'));
+        const list = Array.isArray(rawModels) ? rawModels : [];
+        if (list.some((m) => m === null || typeof m !== 'object' || Array.isArray(m)))
+            return refuse('catalog_unreadable', en('onboard.plan.modelsItemNotObject'));
+        const models = list.map((m) => ({ ...m }));
+        const envModel = [input.effectiveEnv?.['MODEL_ID'], input.effectiveEnv?.['MODEL_CHEAP_ID']].find((v) => typeof v === 'string' && v.trim() !== '');
+        if (envModel !== undefined && !models.some((m) => m['enabled'] !== false)) {
+            return refuse('env_catalog_present', en('onboard.plan.envCatalogPresent', { model: envModel }));
+        }
+        const rawEnv = input.settingsEnv;
+        if (rawEnv !== undefined && (rawEnv === null || typeof rawEnv !== 'object' || Array.isArray(rawEnv)))
+            return refuse('catalog_unreadable', en('onboard.plan.envNotObject'));
+        const prevEnv = rawEnv === undefined ? {} : { ...rawEnv };
+        const e = input.entry;
+        const isShellSlot = (ref) => typeof ref === 'string' && ref.startsWith(KEY_SLOT_PREFIX) && typeof prevEnv[ref] === 'string';
+        const targetKey = routeKeyOf(e.baseUrl);
+        if (targetKey === undefined)
+            return refuse('credential_unpaired', en('onboard.catalog.judgeAbsent', { name: e.modelId }));
+        const sameTarget = (m) => m['id'] === e.modelId && m['api'] === e.api && typeof m['baseUrl'] === 'string' && routeKeyOf(m['baseUrl']) === targetKey;
+        const existingIdx = models.findIndex((m) => sameTarget(m) && m['enabled'] !== false && m['sealedApiKey'] === undefined && (m['apiKeyEnv'] === undefined || isShellSlot(m['apiKeyEnv'])));
+        const taken = new Set(models.map((m) => (typeof m['name'] === 'string' ? m['name'] : '')).filter((n) => n !== ''));
+        const name = existingIdx >= 0 ? String(models[existingIdx]['name']) : poolEntryNameOf(e.modelId, e.channel, taken);
+        const existingRef = existingIdx >= 0 ? models[existingIdx]['apiKeyEnv'] : undefined;
+        const sharedByOther = typeof existingRef === 'string' &&
+            models.some((m, i) => i !== existingIdx && typeof m['apiKeyEnv'] === 'string' && m['apiKeyEnv'].toUpperCase() === existingRef.toUpperCase());
+        let keyEnv;
+        if (isShellSlot(existingRef) && !sharedByOther) {
+            keyEnv = existingRef;
+        }
+        else {
+            const used = new Set();
+            for (const m of models)
+                if (typeof m['apiKeyEnv'] === 'string')
+                    used.add(m['apiKeyEnv'].toUpperCase());
+            for (const k of Object.keys(prevEnv))
+                used.add(k.toUpperCase());
+            for (const [k, v] of Object.entries(input.effectiveEnv ?? {}))
+                if (typeof v === 'string')
+                    used.add(k.toUpperCase());
+            const baseSlot = keyEnvNameForEntry(name);
+            keyEnv = baseSlot;
+            for (let i = 2; used.has(keyEnv.toUpperCase()); i++)
+                keyEnv = `${baseSlot}_${i}`;
+        }
+        if (carriesKey(name, e.apiKey) || carriesKey(keyEnv, e.apiKey))
+            return refuse('input', en('onboard.input.keyInFields'));
+        const base = existingIdx >= 0 ? models[existingIdx] : {};
+        let entry = {
+            ...base,
+            name,
+            id: e.modelId,
+            provider: e.api === 'anthropic-messages' ? 'anthropic' : 'gateway',
+            api: e.api,
+            baseUrl: e.baseUrl,
+            contextWindow: typeof base['contextWindow'] === 'number' ? base['contextWindow'] : e.contextWindow,
+            maxTokens: typeof base['maxTokens'] === 'number' ? base['maxTokens'] : e.maxTokens,
+            apiKeyEnv: keyEnv,
+            semaChannel: typeof base['semaChannel'] === 'string' ? base['semaChannel'] : e.channel,
+            semaLabel: typeof base['semaLabel'] === 'string' ? base['semaLabel'] : e.providerName,
+            semaProbe: input.probe.verdict,
+            semaProbeAt: input.now,
+        };
+        if (input.thinking !== undefined) {
+            const probed = applyProbeToEntry({ ...(typeof entry['reasoning'] === 'boolean' ? { reasoning: entry['reasoning'] } : {}), ...(entry['compat'] !== undefined ? { compat: entry['compat'] } : {}) }, input.thinking);
+            const next = { ...entry };
+            if (typeof probed.reasoning === 'boolean')
+                next['reasoning'] = probed.reasoning;
+            if (probed.compat !== undefined)
+                next['compat'] = probed.compat;
+            else
+                delete next['compat'];
+            entry = next;
+        }
+        const envView = { ...input.effectiveEnv, [keyEnv]: e.apiKey };
+        const issue = entryCredentialIssue(entry, envView);
+        if (issue !== undefined)
+            return refuse('credential_unpaired', issue);
+        if (existingIdx >= 0)
+            models[existingIdx] = entry;
+        else
+            models.push(entry);
+        const nextDoc = { ...doc, models };
+        if (input.makeDefault) {
+            const prevRoles = doc['roles'];
+            const roles = prevRoles !== null && typeof prevRoles === 'object' && !Array.isArray(prevRoles) ? { ...prevRoles } : {};
+            roles['default'] = { model: name };
+            nextDoc['roles'] = roles;
+        }
+        const otherIssues = [];
+        for (const m of models) {
+            if (m['enabled'] === false || m['name'] === name)
+                continue;
+            const other = entryCredentialIssue(m, envView);
+            if (other !== undefined) {
+                otherIssues.push(Object.freeze({ name: typeof m['name'] === 'string' ? m['name'] : '?', modelId: typeof m['id'] === 'string' ? m['id'] : '?', issue: say(other) }));
+            }
+        }
+        return Object.freeze({
+            ok: true,
+            entryName: name,
+            keyEnv,
+            updatedExisting: existingIdx >= 0,
+            nextModelsDoc: nextDoc,
+            nextSettingsEnv: { ...prevEnv, [keyEnv]: e.apiKey },
+            otherIssues: Object.freeze(otherIssues),
+        });
+    }
+    catch {
+        return refuse('input', en('onboard.refusal.input'));
+    }
+}
+const REFUSAL_KEYS = {
+    input: 'onboard.refusal.input',
+    probe_failed: 'onboard.refusal.probeFailed',
+    probe_unverified: 'onboard.refusal.probeUnverified',
+    credential_unpaired: 'onboard.refusal.credentialUnpaired',
+    catalog_unreadable: 'onboard.refusal.catalogUnreadable',
+    write_conflict: 'onboard.refusal.writeConflict',
+    write_failed: 'onboard.refusal.writeFailed',
+    engine_is_remote: 'onboard.refusal.engineIsRemote',
+    env_catalog_present: 'onboard.refusal.envCatalogPresent',
+};
+export function onboardRefusalText(refusal, lang) {
+    const known = ONBOARD_REFUSALS.find((w) => w === refusal) ?? 'input';
+    return renderMessage(msg(REFUSAL_KEYS[known]), lang);
+}

package/dist/model/tierVocabulary.d.ts

@@ -1,10 +1,12 @@
 import { CORE_DEFAULT_TIER_ORDER } from '../generated/engineFactTables.js';
+import type { UiLanguage } from '../env/uiLanguage.js';
 export type Tier = (typeof CORE_DEFAULT_TIER_ORDER)[number];
 export declare const TIER_ORDER: readonly Tier[];
 export declare const SURFACED_TIERS: readonly Tier[];
 export declare const CC_TIER_ALIASES: Readonly<Record<string, Tier>>;
 export declare const DEFAULT_TIER: Tier;
 export declare const TIER_BLURBS: Readonly<Record<Tier, string>>;
+export declare function tierBlurb(tier: Tier, lang?: UiLanguage): string;
 export type TierGroupDef = {
     tiers: Partial<Record<Tier, string>>;
     defaultTier?: Tier;

package/dist/model/tierVocabulary.js

@@ -1,15 +1,27 @@
 import { CORE_CC_MODEL_TIER_ALIASES, CORE_DEFAULT_TIER_ORDER } from '../generated/engineFactTables.js';
+import { EN_MESSAGES } from '../i18n/messages.en.js';
+import { msg, renderMessage } from '../i18n/translate.js';
 export const TIER_ORDER = CORE_DEFAULT_TIER_ORDER;
 export const SURFACED_TIERS = ['max', 'pro', 'flash', 'lite'];
 export const CC_TIER_ALIASES = CORE_CC_MODEL_TIER_ALIASES;
 export const DEFAULT_TIER = 'pro';
+const TIER_BLURB_KEYS = Object.freeze({
+    ultra: 'model.tier.blurb.ultra',
+    max: 'model.tier.blurb.max',
+    pro: 'model.tier.blurb.pro',
+    flash: 'model.tier.blurb.flash',
+    lite: 'model.tier.blurb.lite',
+});
 export const TIER_BLURBS = {
-    ultra: 'reserved above max — binds when a stronger model lands',
-    max: 'hardest problems — deep reasoning, big refactors',
-    pro: 'everyday driving — the default tier',
-    flash: 'fast + cheap — titles, recaps, volume work',
-    lite: 'cheapest — bulk classification, simple lookups',
+    ultra: EN_MESSAGES[TIER_BLURB_KEYS.ultra],
+    max: EN_MESSAGES[TIER_BLURB_KEYS.max],
+    pro: EN_MESSAGES[TIER_BLURB_KEYS.pro],
+    flash: EN_MESSAGES[TIER_BLURB_KEYS.flash],
+    lite: EN_MESSAGES[TIER_BLURB_KEYS.lite],
 };
+export function tierBlurb(tier, lang) {
+    return typeof tier === 'string' && Object.hasOwn(TIER_BLURB_KEYS, tier) ? renderMessage(msg(TIER_BLURB_KEYS[tier]), lang) : '';
+}
 export const isTier = (v) => typeof v === 'string' && TIER_ORDER.includes(v);
 export function resolveTierBinding(def, tier) {
     const direct = def.tiers[tier];

package/dist/modelCapabilityProbe.d.ts

@@ -1,3 +1,5 @@
+import type { ModelApiWord } from './model/providerPresets.js';
+import type { UiLanguage } from './env/uiLanguage.js';
 export interface OpenAICompletionsProbeBody {
     model: string;
     messages: ReadonlyArray<{
@@ -66,4 +68,67 @@ type ProbeWritableEntry = {
     compat?: unknown;
 };
 export declare function applyProbeToEntry<T extends ProbeWritableEntry>(entry: T, result: ModelProbeResult): T;
+export declare const PROBE_VERDICTS: readonly ["ok", "auth", "unreachable", "model", "shape", "busy", "no_token", "other"];
+export type ProbeVerdictWord = (typeof PROBE_VERDICTS)[number];
+export type ProbeAnswerOutcome = 'error' | 'not_model' | 'ended';
+export interface ProbeVerdict {
+    readonly verdict: ProbeVerdictWord;
+    readonly httpStatus?: number;
+    readonly waitedMs?: number;
+    readonly path?: string;
+    readonly apiError?: string;
+    readonly outcome?: ProbeAnswerOutcome;
+    readonly nearModelId?: string;
+    readonly cause?: string;
+}
+export interface LivenessFetchInit {
+    readonly method: 'GET' | 'POST';
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: string;
+    readonly signal: AbortSignal;
+}
+export interface LivenessBodyReader {
+    read(): Promise<{
+        readonly done: boolean;
+        readonly value?: Uint8Array | undefined;
+    }>;
+    cancel(): Promise<void>;
+}
+export interface LivenessResponse {
+    readonly status: number;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    readonly body: {
+        getReader(): LivenessBodyReader;
+    } | null;
+    text(): Promise<string>;
+}
+export type LivenessFetch = (url: string, init: LivenessFetchInit) => Promise<LivenessResponse>;
+export interface LivenessProbeInput {
+    readonly api: ModelApiWord;
+    readonly baseUrl: string;
+    readonly modelId?: string;
+    readonly fetch: LivenessFetch;
+    readonly firstTokenBudgetMs: number;
+    readonly catalogBudgetMs: number;
+    readonly signal?: AbortSignal;
+    readonly now?: () => number;
+    readonly redact?: (text: string) => string;
+    readonly requestUrl?: (path: string) => string;
+}
+export declare function probeModelLiveness(input: LivenessProbeInput): Promise<ProbeVerdict>;
+export type ProbeVerdictRecourse = 'switch_model' | 'check_credentials';
+export interface ProbeVerdictNotice {
+    readonly line: string;
+    readonly recourse?: ProbeVerdictRecourse;
+}
+export interface ProbeVerdictFacts {
+    readonly verdict?: string;
+    readonly httpStatus?: number;
+    readonly waitedMs?: number;
+}
+export declare function probeVerdictNotice(facts: ProbeVerdictFacts | null | undefined, ctx?: {
+    readonly modelName?: string;
+}, lang?: UiLanguage): ProbeVerdictNotice;
 export {};