@sema-agent/client-core 0.98.0 → 0.99.0

package/dist/modelCapabilityProbe.js

@@ -1,3 +1,7 @@
+import { displayUntrusted } from './displayUntrusted.js';
+import { abortableSleep } from './abortableSleep.js';
+import { readThrownSlot } from './wireFailureShape.js';
+import { guardedRead, readOwnDataValue } from './ownKey.js';
 export const THINKING_FORMATS = Object.freeze([
     'openai',
     'openrouter',
@@ -142,3 +146,599 @@ export function applyProbeToEntry(entry, result) {
     }
     return entry;
 }
+export const PROBE_VERDICTS = Object.freeze(['ok', 'auth', 'unreachable', 'model', 'shape', 'busy', 'no_token', 'other']);
+function isBusyStatus(status) {
+    return status === 429 || status === 503 || status === 529;
+}
+function looksBusyError(apiError) {
+    return apiError !== undefined && /overload|rate.?limit|too many requests|too busy|server busy|capacity/i.test(apiError);
+}
+function apiErrorOf(parsed) {
+    const e = parsed?.error;
+    if (!e || typeof e !== 'object')
+        return undefined;
+    return [e.code ?? e.type, e.message].filter(Boolean).join(': ') || undefined;
+}
+function extractApiError(body) {
+    try {
+        return apiErrorOf(JSON.parse(body));
+    }
+    catch {
+        return undefined;
+    }
+}
+function maskedByHost(raw, redact) {
+    if (redact === undefined)
+        return raw;
+    try {
+        const out = redact(raw);
+        return typeof out === 'string' ? out : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function shownApiError(raw, redact) {
+    if (raw === undefined)
+        return undefined;
+    const masked = maskedByHost(raw, redact);
+    if (masked === undefined)
+        return undefined;
+    const shown = displayUntrusted(masked, { max: 200 });
+    return shown.trim() === '' ? undefined : shown;
+}
+function looksLikeModelError(status, apiError) {
+    if (status !== 400 && status !== 404 && status !== 422)
+        return false;
+    if (!apiError)
+        return status === 404;
+    return /model/i.test(apiError);
+}
+const MESSAGES_PATH = '/v1/messages';
+const COMPLETIONS_PATH = '/chat/completions';
+const MODELS_PATH_ANTHROPIC = '/v1/models';
+const MODELS_PATH_OPENAI = '/models';
+function verdictRequestBody(modelId) {
+    return JSON.stringify({ model: modelId ?? '', max_tokens: 1, messages: [{ role: 'user', content: 'hi' }], stream: true });
+}
+function judgeMessagesFailure(status, body, hasModelId, near, redact) {
+    if (status === 401 || status === 403)
+        return { verdict: 'auth', httpStatus: status, path: MESSAGES_PATH };
+    const apiError = extractApiError(body);
+    const shown = shownApiError(apiError, redact);
+    const ev = { httpStatus: status, path: MESSAGES_PATH, ...(shown !== undefined ? { apiError: shown } : {}) };
+    if (isBusyStatus(status) || looksBusyError(apiError))
+        return { verdict: 'busy', ...ev };
+    if (status === 404 && !apiError)
+        return { verdict: 'shape', httpStatus: status, path: MESSAGES_PATH };
+    if (looksLikeModelError(status, apiError)) {
+        if (!hasModelId)
+            return { verdict: 'ok', httpStatus: status, path: MESSAGES_PATH };
+        return { verdict: 'model', ...ev, ...(near !== undefined ? { nearModelId: near } : {}) };
+    }
+    if (!hasModelId && status >= 400 && status < 500 && apiError)
+        return { verdict: 'ok', httpStatus: status, path: MESSAGES_PATH };
+    return { verdict: 'other', ...ev };
+}
+function judgeCompletionsFailure(status, body, near, redact) {
+    if (status === 401 || status === 403)
+        return { verdict: 'auth', httpStatus: status, path: COMPLETIONS_PATH };
+    const apiError = extractApiError(body);
+    const shown = shownApiError(apiError, redact);
+    const ev = { httpStatus: status, path: COMPLETIONS_PATH, ...(shown !== undefined ? { apiError: shown } : {}) };
+    if (isBusyStatus(status) || looksBusyError(apiError))
+        return { verdict: 'busy', ...ev };
+    if (looksLikeModelError(status, apiError))
+        return { verdict: 'model', ...ev, ...(near !== undefined ? { nearModelId: near } : {}) };
+    return { verdict: 'other', ...ev };
+}
+function judgeAnswer(path, status, answer, waitedMs, redact) {
+    const at = { httpStatus: status, path };
+    switch (answer.kind) {
+        case 'token':
+            return { verdict: 'ok', ...at, waitedMs };
+        case 'no_token':
+            return { verdict: 'no_token', ...at, waitedMs };
+        case 'error': {
+            const shown = shownApiError(answer.apiError, redact);
+            return { verdict: looksBusyError(answer.apiError) ? 'busy' : 'shape', ...at, outcome: 'error', ...(shown !== undefined ? { apiError: shown } : {}) };
+        }
+        case 'not_model':
+            return { verdict: 'shape', ...at, outcome: 'not_model' };
+        case 'ended':
+            return { verdict: 'other', ...at, outcome: 'ended' };
+    }
+}
+const ANSWER_SCAN_CAP = 1 << 20;
+const SSE_FIELD_HEADS = ['data:', 'event:', 'id:', 'retry:'];
+function nonEmptyText(v) {
+    return typeof v === 'string' && v !== '';
+}
+function positiveCount(v) {
+    return typeof v === 'number' && v > 0;
+}
+function anthropicBlockHasOutput(b) {
+    if (b === null || typeof b !== 'object')
+        return false;
+    const o = b;
+    return nonEmptyText(o.text) || nonEmptyText(o.thinking) || nonEmptyText(o.data) || o.type === 'tool_use';
+}
+function completionsChoiceHasOutput(c) {
+    if (!isChatChoiceShape(c))
+        return false;
+    const o = c;
+    for (const part of [o.delta, o.message]) {
+        if (part === null || typeof part !== 'object')
+            continue;
+        const d = part;
+        if (nonEmptyText(d.content) || nonEmptyText(d.reasoning_content) || nonEmptyText(d.reasoning))
+            return true;
+        if (Array.isArray(d.tool_calls) && d.tool_calls.length > 0)
+            return true;
+    }
+    return o.finish_reason === 'length';
+}
+function isTokenFrame(obj, api) {
+    if (api === 'anthropic-messages') {
+        if (obj.type === 'content_block_delta') {
+            const d = obj.delta;
+            return d !== null && d !== undefined && typeof d === 'object' && (nonEmptyText(d.text) || nonEmptyText(d.thinking) || nonEmptyText(d.partial_json));
+        }
+        if (obj.type === 'content_block_start')
+            return anthropicBlockHasOutput(obj.content_block);
+        if (obj.type === 'message_delta')
+            return obj.delta?.stop_reason === 'max_tokens';
+        return false;
+    }
+    if (Array.isArray(obj.choices) && obj.choices.some(completionsChoiceHasOutput))
+        return true;
+    return positiveCount(obj.usage?.completion_tokens);
+}
+function isChatChoiceShape(c) {
+    if (c === null || typeof c !== 'object')
+        return false;
+    const o = c;
+    return (o.delta !== null && typeof o.delta === 'object') || (o.message !== null && typeof o.message === 'object');
+}
+function isOwnLaneFrame(obj, api) {
+    if (api === 'anthropic-messages')
+        return typeof obj.type === 'string';
+    return Array.isArray(obj.choices) && (obj.choices.length === 0 || obj.choices.some(isChatChoiceShape));
+}
+function judgeJsonBody(text, contentType, api) {
+    let obj;
+    try {
+        obj = JSON.parse(text);
+    }
+    catch {
+        return { kind: 'not_model', contentType };
+    }
+    if (obj === null || typeof obj !== 'object')
+        return { kind: 'not_model', contentType };
+    const o = obj;
+    const apiError = apiErrorOf(o);
+    if (apiError !== undefined || o.type === 'error')
+        return { kind: 'error', ...(apiError !== undefined ? { apiError } : {}) };
+    const usage = (o.usage ?? null);
+    if (api === 'anthropic-messages') {
+        if (o.type !== 'message' && !Array.isArray(o.content))
+            return { kind: 'not_model', contentType };
+        const hasOutput = (Array.isArray(o.content) && o.content.some(anthropicBlockHasOutput)) || o.stop_reason === 'max_tokens' || positiveCount(usage?.output_tokens);
+        return hasOutput ? { kind: 'token' } : { kind: 'ended' };
+    }
+    if (Array.isArray(o.choices)) {
+        if (o.choices.length > 0 && !o.choices.some(isChatChoiceShape))
+            return { kind: 'not_model', contentType };
+        return o.choices.some(completionsChoiceHasOutput) || positiveCount(usage?.completion_tokens) ? { kind: 'token' } : { kind: 'ended' };
+    }
+    return { kind: 'not_model', contentType };
+}
+function createAnswerScanner(contentType, api) {
+    const ct = contentType.slice(0, 120);
+    let mode = /event-stream/i.test(ct) ? 'sse' : /json/i.test(ct) ? 'json' : undefined;
+    let buf = '';
+    let event = '';
+    let data = [];
+    let settled;
+    let sawOwn = false;
+    let sawForeign = false;
+    const dispatch = () => {
+        if (data.length === 0) {
+            event = '';
+            return;
+        }
+        const payload = data.join('\n');
+        const ev = event;
+        data = [];
+        event = '';
+        if (payload.trim() === '[DONE]')
+            return;
+        let obj;
+        try {
+            obj = JSON.parse(payload);
+        }
+        catch {
+            obj = undefined;
+        }
+        if (obj === null || typeof obj !== 'object')
+            return;
+        const o = obj;
+        const apiError = apiErrorOf(o);
+        if (ev === 'error' || o.type === 'error' || apiError !== undefined) {
+            settled = { kind: 'error', ...(apiError !== undefined ? { apiError } : {}) };
+            return;
+        }
+        if (isTokenFrame(o, api))
+            settled = { kind: 'token' };
+        else if (isOwnLaneFrame(o, api))
+            sawOwn = true;
+        else
+            sawForeign = true;
+    };
+    const scanSse = () => {
+        let nl = buf.indexOf('\n');
+        while (nl !== -1 && settled === undefined) {
+            const line = buf.slice(0, nl).replace(/\r$/, '');
+            buf = buf.slice(nl + 1);
+            if (line === '')
+                dispatch();
+            else if (line.startsWith(':')) {
+            }
+            else {
+                const colon = line.indexOf(':');
+                const field = colon === -1 ? line : line.slice(0, colon);
+                const value = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '');
+                if (field === 'event')
+                    event = value;
+                else if (field === 'data')
+                    data.push(value);
+            }
+            nl = buf.indexOf('\n');
+        }
+    };
+    return {
+        push(chunk) {
+            if (settled !== undefined)
+                return settled;
+            buf += chunk;
+            if (mode === undefined) {
+                const head = buf.trimStart();
+                if (head === '')
+                    return undefined;
+                const c = head[0];
+                if (c === '{' || c === '[')
+                    mode = 'json';
+                else if (/^(data|event|id|retry):/.test(head) || c === ':')
+                    mode = 'sse';
+                else if (SSE_FIELD_HEADS.some((f) => f.startsWith(head)))
+                    return undefined;
+                else
+                    return (settled = { kind: 'not_model', contentType: ct });
+            }
+            if (buf.length > ANSWER_SCAN_CAP)
+                return (settled = { kind: 'not_model', contentType: ct });
+            if (mode === 'sse')
+                scanSse();
+            return settled;
+        },
+        finish() {
+            if (settled !== undefined)
+                return settled;
+            if (mode === 'json')
+                return judgeJsonBody(buf, ct, api);
+            if (mode === 'sse') {
+                buf += '\n\n';
+                scanSse();
+                if (settled !== undefined)
+                    return settled;
+                return sawForeign && !sawOwn ? { kind: 'not_model', contentType: ct } : { kind: 'ended' };
+            }
+            return buf.trim() === '' ? { kind: 'ended' } : { kind: 'not_model', contentType: ct };
+        },
+    };
+}
+function nearestListedId(body, modelId) {
+    const data = body?.data;
+    if (!Array.isArray(data))
+        return undefined;
+    const ids = data.map((x) => x?.id).filter((x) => typeof x === 'string');
+    if (ids.includes(modelId))
+        return undefined;
+    const norm = (x) => x.toLowerCase().replace(/[^a-z0-9]+/g, '');
+    const target = norm(modelId);
+    for (const len of [6, 5, 4]) {
+        const stem = target.slice(0, len);
+        if (stem.length < len)
+            continue;
+        const hit = ids.find((i) => norm(i).startsWith(stem));
+        if (hit !== undefined)
+            return hit;
+    }
+    return undefined;
+}
+function nearestFromCatalogText(text, modelId) {
+    try {
+        return nearestListedId(JSON.parse(text), modelId);
+    }
+    catch {
+        return undefined;
+    }
+}
+function unwrapFetchCause(e) {
+    const parts = [];
+    let cur = e;
+    for (let i = 0; i < 4 && cur !== null && typeof cur === 'object'; i++) {
+        const code = readThrownSlot(cur, 'code');
+        const message = readThrownSlot(cur, 'message');
+        const c = typeof code === 'string' && code !== '' ? code : undefined;
+        const m = typeof message === 'string' && message !== '' ? message : undefined;
+        if (c !== undefined)
+            parts.push(m !== undefined && m !== c ? `${c} ${m}` : c);
+        else if (m !== undefined)
+            parts.push(m);
+        cur = readThrownSlot(cur, 'cause');
+    }
+    if (parts.length === 0 && typeof e === 'string')
+        parts.push(e);
+    return [...new Set(parts)].join(' ← ');
+}
+function shownCause(e, redact) {
+    const masked = maskedByHost(unwrapFetchCause(e), redact);
+    if (masked === undefined)
+        return undefined;
+    const shown = displayUntrusted(masked, { max: 160 });
+    return shown.trim() === '' ? undefined : shown;
+}
+const MAX_TIMER_MS = 2_147_483_647;
+function probeDeadline(ms, cancel) {
+    const ctl = new AbortController();
+    const stop = new AbortController();
+    let expired = false;
+    const gone = new Promise((_resolve, reject) => {
+        const fire = () => reject(Object.assign(new Error('aborted'), { name: 'AbortError' }));
+        if (ctl.signal.aborted)
+            fire();
+        else
+            ctl.signal.addEventListener('abort', fire, { once: true });
+    });
+    gone.catch(() => undefined);
+    void abortableSleep(Math.min(ms, MAX_TIMER_MS), stop.signal).then(() => {
+        if (stop.signal.aborted)
+            return;
+        expired = true;
+        ctl.abort();
+    });
+    const onCancel = () => ctl.abort();
+    if (cancel !== undefined) {
+        if (cancel.aborted)
+            ctl.abort();
+        else
+            cancel.addEventListener('abort', onCancel, { once: true });
+    }
+    return {
+        signal: ctl.signal,
+        expired: () => expired,
+        abort: () => {
+            stop.abort();
+            cancel?.removeEventListener('abort', onCancel);
+            ctl.abort();
+        },
+        race: (p) => Promise.race([p, gone]),
+    };
+}
+async function getCatalogText(fetchIt, url, headers, timeoutMs, cancel) {
+    const d = probeDeadline(timeoutMs, cancel);
+    try {
+        const res = await d.race(fetchIt(url, { method: 'GET', headers, signal: d.signal }));
+        let text = '';
+        try {
+            text = await d.race(res.text());
+        }
+        catch {
+            text = '';
+        }
+        return { status: res.status, text };
+    }
+    finally {
+        d.abort();
+    }
+}
+async function postForFirstToken(fetchIt, api, url, path, headers, body, deadlineMs, cancel, now, redact) {
+    const d = probeDeadline(deadlineMs, cancel);
+    const startedAt = now();
+    try {
+        const res = await d.race(fetchIt(url, { method: 'POST', headers, body, signal: d.signal }));
+        if (res.status < 200 || res.status >= 300) {
+            let text = '';
+            try {
+                text = await d.race(res.text());
+            }
+            catch {
+                text = '';
+            }
+            return { kind: 'status', status: res.status, body: text };
+        }
+        const scanner = createAnswerScanner(res.headers.get('content-type') ?? '', api);
+        const pastDeadline = () => d.expired() || now() - startedAt >= deadlineMs;
+        const done = (raw) => {
+            const answer = raw.kind === 'token' && pastDeadline() ? { kind: 'no_token' } : raw;
+            return { kind: 'answer', verdict: judgeAnswer(path, res.status, answer, answer.kind === 'no_token' ? deadlineMs : now() - startedAt, redact) };
+        };
+        const stream = res.body;
+        if (stream === undefined || stream === null) {
+            let text = '';
+            try {
+                text = await d.race(res.text());
+            }
+            catch {
+                return done(d.signal.aborted ? { kind: 'no_token' } : scanner.finish());
+            }
+            if (pastDeadline())
+                return done({ kind: 'no_token' });
+            return done(scanner.push(text) ?? scanner.finish());
+        }
+        const reader = stream.getReader();
+        const decoder = new TextDecoder();
+        try {
+            for (;;) {
+                const { value, done: eof } = await d.race(reader.read());
+                if (pastDeadline())
+                    return done({ kind: 'no_token' });
+                if (eof)
+                    return done(scanner.push(decoder.decode()) ?? scanner.finish());
+                const settled = scanner.push(decoder.decode(value, { stream: true }));
+                if (settled !== undefined)
+                    return done(settled);
+            }
+        }
+        catch {
+            return done(d.signal.aborted ? { kind: 'no_token' } : scanner.finish());
+        }
+        finally {
+            reader.cancel().catch(() => undefined);
+        }
+    }
+    finally {
+        d.abort();
+    }
+}
+export async function probeModelLiveness(input) {
+    try {
+        return await livenessOf(input);
+    }
+    catch (e) {
+        const cause = shownCause(e, redactOf(input));
+        return { verdict: 'unreachable', ...(cause !== undefined ? { cause } : {}) };
+    }
+}
+function redactOf(input) {
+    return typeof input.redact === 'function' ? input.redact : undefined;
+}
+async function livenessOf(input) {
+    const budget = input.firstTokenBudgetMs;
+    if (typeof budget !== 'number' || !Number.isFinite(budget) || budget <= 0)
+        return { verdict: 'unreachable', waitedMs: 0 };
+    const catalogBudget = typeof input.catalogBudgetMs === 'number' && Number.isFinite(input.catalogBudgetMs) && input.catalogBudgetMs > 0 ? input.catalogBudgetMs : budget;
+    const now = typeof input.now === 'function' ? input.now : Date.now;
+    const base = input.baseUrl.replace(/\/+$/, '');
+    const modelId = typeof input.modelId === 'string' && input.modelId.length > 0 ? input.modelId : undefined;
+    const anthropic = input.api === 'anthropic-messages';
+    const getHeaders = anthropic ? { 'anthropic-version': '2023-06-01' } : {};
+    const postHeaders = { ...getHeaders, 'content-type': 'application/json' };
+    const fetchIt = input.fetch;
+    const redact = redactOf(input);
+    const urlOf = (path) => {
+        if (typeof input.requestUrl !== 'function')
+            return `${base}${path}`;
+        const u = input.requestUrl(path);
+        if (typeof u !== 'string' || u === '')
+            throw new TypeError('request URL not built');
+        return u;
+    };
+    if (anthropic) {
+        const listCancel = new AbortController();
+        const nearP = modelId !== undefined
+            ? getCatalogText(fetchIt, urlOf(MODELS_PATH_ANTHROPIC), getHeaders, catalogBudget, listCancel.signal)
+                .then((r) => (r.status >= 200 && r.status < 300 ? nearestFromCatalogText(r.text, modelId) : undefined))
+                .catch(() => undefined)
+            : Promise.resolve(undefined);
+        try {
+            let r;
+            try {
+                r = await postForFirstToken(fetchIt, input.api, urlOf(MESSAGES_PATH), MESSAGES_PATH, postHeaders, verdictRequestBody(modelId), budget, input.signal, now, redact);
+            }
+            catch (e) {
+                if (input.signal?.aborted !== true && isAbortLike(e))
+                    return { verdict: 'unreachable', path: MESSAGES_PATH, waitedMs: budget };
+                const cause = shownCause(e, redact);
+                return { verdict: 'unreachable', path: MESSAGES_PATH, ...(cause !== undefined ? { cause } : {}) };
+            }
+            if (r.kind === 'answer')
+                return r.verdict;
+            const first = judgeMessagesFailure(r.status, r.body, modelId !== undefined, undefined, redact);
+            if (first.verdict !== 'model')
+                return first;
+            const near = await nearP;
+            return near === undefined ? first : judgeMessagesFailure(r.status, r.body, true, shownApiError(near, redact), redact);
+        }
+        finally {
+            listCancel.abort();
+        }
+    }
+    const gate = await getCatalogText(fetchIt, urlOf(MODELS_PATH_OPENAI), getHeaders, catalogBudget, input.signal);
+    if (gate.status === 401 || gate.status === 403)
+        return { verdict: 'auth', httpStatus: gate.status, path: '/models' };
+    if (isBusyStatus(gate.status))
+        return { verdict: 'busy', httpStatus: gate.status, path: '/models' };
+    if (gate.status < 200 || gate.status >= 300)
+        return { verdict: 'other', httpStatus: gate.status, path: '/models' };
+    const near = modelId !== undefined ? nearestFromCatalogText(gate.text, modelId) : undefined;
+    if (modelId === undefined)
+        return { verdict: 'ok', httpStatus: gate.status, path: '/models' };
+    try {
+        const r = await postForFirstToken(fetchIt, input.api, urlOf(COMPLETIONS_PATH), COMPLETIONS_PATH, postHeaders, verdictRequestBody(modelId), budget, input.signal, now, redact);
+        if (r.kind === 'answer')
+            return r.verdict;
+        return judgeCompletionsFailure(r.status, r.body, shownApiError(near, redact), redact);
+    }
+    catch (e) {
+        if (input.signal?.aborted !== true && isAbortLike(e))
+            return { verdict: 'unreachable', path: COMPLETIONS_PATH, waitedMs: budget };
+        const cause = shownCause(e, redact);
+        return { verdict: 'unreachable', path: COMPLETIONS_PATH, ...(cause !== undefined ? { cause } : {}) };
+    }
+}
+function isAbortLike(e) {
+    return readThrownSlot(e, 'name') === 'AbortError' || /abort/i.test(unwrapFetchCause(e));
+}
+function probeSeconds(ms) {
+    if (ms < 100)
+        return '<0.1s';
+    const sec = ms / 1000;
+    return `${Number.isInteger(sec) ? sec : sec.toFixed(1)}s`;
+}
+const readFacts = (o, key) => guardedRead(() => readOwnDataValue(o, key));
+export function probeVerdictNotice(facts, ctx) {
+    const rawWord = readFacts(facts, 'verdict');
+    const word = typeof rawWord === 'string' && PROBE_VERDICTS.includes(rawWord) ? rawWord : 'other';
+    const rawStatus = readFacts(facts, 'httpStatus');
+    const status = typeof rawStatus === 'number' && Number.isInteger(rawStatus) && rawStatus >= 100 && rawStatus <= 999 ? rawStatus : undefined;
+    const rawWaited = readFacts(facts, 'waitedMs');
+    const waited = typeof rawWaited === 'number' && Number.isFinite(rawWaited) && rawWaited >= 0 ? rawWaited : undefined;
+    const http = status === undefined ? '' : ` (HTTP ${status})`;
+    const rawModel = readFacts(ctx, 'modelName');
+    const model = typeof rawModel === 'string' && rawModel.trim() !== '' ? displayUntrusted(rawModel).trim() : '';
+    const prefix = model === '' ? '' : `${model}: `;
+    let line;
+    let recourse;
+    switch (word) {
+        case 'ok':
+            line = `The model answered${waited === undefined ? '' : ` — first token after ${probeSeconds(waited)}`}`;
+            break;
+        case 'auth':
+            line = `The model service rejected the API key${http}`;
+            recourse = 'check_credentials';
+            break;
+        case 'unreachable':
+            line = `Could not reach the model service${waited === undefined ? '' : ` — no response within ${probeSeconds(waited)}`}`;
+            break;
+        case 'model':
+            line = `The model service does not recognise this model id${http}`;
+            break;
+        case 'shape':
+            line = `This address does not offer the expected interface${http} — check the API shape`;
+            break;
+        case 'busy':
+            line = `The model service is busy right now${http} — retry later or switch model`;
+            recourse = 'switch_model';
+            break;
+        case 'no_token':
+            line = `The model service answered but sent no token${waited === undefined ? '' : ` within ${probeSeconds(waited)}`} — it may be overloaded`;
+            recourse = 'switch_model';
+            break;
+        case 'other':
+            line = `The model service gave an unexpected answer${http}`;
+            break;
+    }
+    return Object.freeze(recourse === undefined ? { line: `${prefix}${line}` } : { line: `${prefix}${line}`, recourse });
+}

package/dist/modelIdentityResolvability.d.ts

@@ -1,3 +1,4 @@
+import type { UiLanguage } from './env/uiLanguage.js';
 type ModelIdentityLaneTuple = readonly [
     'processEnv',
     'settingsEnv',
@@ -27,6 +28,8 @@ export type ModelIdentityReading = LocalEngineModelIdentityReading | RemoteEngin
 export type ModelIdentityResolvability = 'resolvable' | 'not_resolvable' | 'unknown';
 export type ModelSetupDecision = 'offer_setup' | 'offer_route_setup' | 'explain_unconfigured' | 'explain_route_gap' | 'explain_route_unconfigurable' | 'proceed';
 export declare function modelIdentityResolvability(reading: ModelIdentityReading): ModelIdentityResolvability;
+export declare function modelRouteGapSentence(lane: ModelIdentityLane, gap: ModelRouteGapReading, lang?: UiLanguage): string | undefined;
+export declare function modelRouteGapFact(gap: ModelRouteGapReading, lang?: UiLanguage): string | undefined;
 export declare function modelIdentityDetail(reading: ModelIdentityReading): string;
 export declare function modelSetupDecision(reading: ModelIdentityReading, hostCanConfigureModel: boolean, hostCanConfigureRoute?: boolean): ModelSetupDecision;
 export declare function modelSetupNotice(decision: ModelSetupDecision): string | null;

package/dist/modelIdentityResolvability.js

@@ -1,5 +1,6 @@
 import { engineCapsLandingOf } from './engineCapsCache.js';
 import { engineWireTarget } from './engineWireTarget.js';
+import { msg, renderMessage } from './i18n/translate.js';
 function laneOrder() {
     return ['processEnv', 'settingsEnv', 'modelCatalogFile', 'followedSettingsFile', 'followedProviderEnv'];
 }
@@ -99,19 +100,30 @@ function analyse(reading) {
 export function modelIdentityResolvability(reading) {
     return analyse(reading).verdict;
 }
+const LANE_LABEL_KEYS = Object.freeze({
+    processEnv: 'model.identity.lane.processEnv',
+    settingsEnv: 'model.identity.lane.settingsEnv',
+    modelCatalogFile: 'model.identity.lane.modelCatalogFile',
+    followedSettingsFile: 'model.identity.lane.followedSettingsFile',
+    followedProviderEnv: 'model.identity.lane.followedProviderEnv',
+});
 function laneLabel(lane) {
-    switch (lane) {
-        case 'processEnv':
-            return 'the environment this client was started with';
-        case 'settingsEnv':
-            return "this client's settings file";
-        case 'modelCatalogFile':
-            return 'the local model catalog file';
-        case 'followedSettingsFile':
-            return "another tool's settings file that this client follows";
-        case 'followedProviderEnv':
-            return 'the provider environment variables this client follows';
-    }
+    return renderMessage(msg(LANE_LABEL_KEYS[lane]));
+}
+const ROUTE_GAP_FACT_KEYS = Object.freeze({
+    endpoint_missing: 'model.identity.routeGap.fact.endpointMissing',
+    lane_credential_missing: 'model.identity.routeGap.fact.laneCredentialMissing',
+});
+const isRouteGapKind = (v) => typeof v === 'string' && Object.hasOwn(ROUTE_GAP_FACT_KEYS, v);
+const isLane = (v) => typeof v === 'string' && Object.hasOwn(LANE_LABEL_KEYS, v);
+function routeGapSentenceRef(lane, gap) {
+    return msg('model.identity.routeGap.sentence', { lane: msg(LANE_LABEL_KEYS[lane]), fact: msg(ROUTE_GAP_FACT_KEYS[gap]) });
+}
+export function modelRouteGapSentence(lane, gap, lang) {
+    return isLane(lane) && isRouteGapKind(gap) ? renderMessage(routeGapSentenceRef(lane, gap), lang) : undefined;
+}
+export function modelRouteGapFact(gap, lang) {
+    return isRouteGapKind(gap) ? renderMessage(msg(ROUTE_GAP_FACT_KEYS[gap]), lang) : undefined;
 }
 function joinPhrases(xs) {
     if (xs.length <= 1)
@@ -133,11 +145,8 @@ export function modelIdentityDetail(reading) {
             }
             return `${laneLabel(a.lane)} supplies a model name for the local engine — whether the engine also has a route to reach that model (an endpoint, or credentials for the channel it names) and whether its gateway accepts the name are separate checks`;
         case 'not_resolvable': {
-            if (a.why === 'route_gap') {
-                return a.gap === 'endpoint_missing'
-                    ? `${laneLabel(a.lane)} supplies a model name, but the local engine has no route to reach it — the model rides the OpenAI-compatible route and no gateway address (MODEL_GATEWAY_BASEURL) is set, and the engine refuses to start without one`
-                    : `${laneLabel(a.lane)} supplies a model name, but the local engine has no route to reach it — the anthropic channel is selected (MODEL_PROVIDER=anthropic), neither ANTHROPIC_API_KEY nor ANTHROPIC_AUTH_TOKEN is set, and there is no gateway address (MODEL_GATEWAY_BASEURL) to fall back to, so the engine cannot start on any route`;
-            }
+            if (a.why === 'route_gap')
+                return renderMessage(routeGapSentenceRef(a.lane, a.gap));
             const others = a.catalogRefused ? a.partial.filter((l) => l !== 'modelCatalogFile') : a.partial;
             const partialClause = others.length > 0
                 ? `${joinPhrases(others.map(laneLabel))} ${others.length > 1 ? 'carry' : 'carries'} part of a model configuration (such as a gateway address or a credential) but no model name`