@sema-agent/client-core 0.97.1 → 0.99.0

package/dist/model/modelsPolicy.js

@@ -34,53 +34,23 @@ function atMentionOf(v) {
         return undefined;
     }
 }
-function atModelAllowlistOf(v) {
-    if (!Array.isArray(v))
-        return { kind: 'unreadable', from: 'atModelAllowlist' };
-    const names = [];
-    let bad = 0;
-    for (let i = 0; i < v.length; i += 1) {
-        const d = Object.getOwnPropertyDescriptor(v, i);
-        const x = d !== undefined && 'value' in d ? d.value : undefined;
-        if (typeof x === 'string' && x.length > 0)
-            names.push(x);
-        else
-            bad += 1;
-    }
-    const value = names.length > 0 ? { mode: 'only', models: names } : { mode: 'all' };
-    return { kind: 'read', value, from: 'atModelAllowlist', unreadableEntries: bad };
-}
 export function modelsPolicyOf(doc) {
     try {
         if (!isRecord(doc))
             return {};
         let defaultModel;
-        let defaultUnreadable = false;
-        if (Object.hasOwn(doc, 'default')) {
-            const d = ownData(doc, 'default');
-            if (typeof d === 'string' && d.length > 0)
-                defaultModel = { name: d, from: 'default' };
-            else
-                defaultUnreadable = true;
-        }
-        if (defaultModel === undefined && !defaultUnreadable) {
-            const roles = ownData(doc, 'roles');
-            const rd = isRecord(roles) ? ownData(roles, 'default') : undefined;
-            const model = isRecord(rd) ? ownData(rd, 'model') : undefined;
-            if (typeof model === 'string' && model.length > 0)
-                defaultModel = { name: model, from: 'roles.default' };
-        }
+        const roles = ownData(doc, 'roles');
+        const rd = isRecord(roles) ? ownData(roles, 'default') : undefined;
+        const model = isRecord(rd) ? ownData(rd, 'model') : undefined;
+        if (typeof model === 'string' && model.length > 0)
+            defaultModel = { name: model };
         let atMention;
         if (Object.hasOwn(doc, 'atMention')) {
             const am = atMentionOf(ownData(doc, 'atMention'));
-            atMention = am === undefined ? { kind: 'unreadable', from: 'atMention' } : { kind: 'read', value: am, from: 'atMention', unreadableEntries: 0 };
-        }
-        else if (Object.hasOwn(doc, 'atModelAllowlist')) {
-            atMention = atModelAllowlistOf(ownData(doc, 'atModelAllowlist'));
+            atMention = am === undefined ? { kind: 'unreadable' } : { kind: 'read', value: am };
         }
         return {
             ...(defaultModel !== undefined ? { defaultModel } : {}),
-            ...(defaultUnreadable ? { defaultUnreadable: true } : {}),
             ...(atMention !== undefined ? { atMention } : {}),
         };
     }

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/subagentModelWord.d.ts

@@ -0,0 +1,31 @@
+import { type LiveModelCatalog } from '../liveModelCatalog.js';
+import type { UiLanguage } from '../env/uiLanguage.js';
+export type SubagentModelWordKind = 'inherit' | 'catalog' | 'tier' | 'cc-alias' | 'best' | 'model-id' | 'passthrough' | 'catalog-unknown' | 'ambiguous' | 'unbound';
+export type SubagentModelWordProblem = 'tiers-inert' | 'chain-unbound' | 'binding-not-in-catalog';
+export interface SubagentModelLocalEngine {
+    readonly engine: 'started-by-this-process';
+    readonly tiers: Readonly<Record<string, string>> | undefined;
+    readonly pool?: readonly {
+        readonly name: string;
+        readonly id?: string;
+    }[];
+}
+export interface SubagentModelWordInput {
+    readonly word?: string | null | undefined;
+    readonly liveCatalog?: LiveModelCatalog | null | undefined;
+    readonly local?: SubagentModelLocalEngine | null | undefined;
+}
+export interface SubagentModelLanding {
+    readonly name: string;
+    readonly via: readonly string[];
+    readonly source: 'local-config';
+}
+export interface SubagentModelWordReading {
+    readonly kind: SubagentModelWordKind;
+    readonly model?: string;
+    readonly landing?: SubagentModelLanding;
+    readonly problem?: SubagentModelWordProblem;
+    readonly label?: string;
+}
+export declare function resolveSubagentModelWord(input: SubagentModelWordInput | null | undefined): SubagentModelWordReading;
+export declare function subagentModelWordProblemLine(word: string, reading: SubagentModelWordReading, lang?: UiLanguage): string | undefined;