talos-code 0.0.1 → 0.1.0

package/dist/provider/control-plane.js

@@ -0,0 +1,135 @@
+import { providerDescriptionText, providerLabelText } from "./provider-text.js";
+import { UNKNOWN_PROVIDER_HEALTH, providerCooldownFromRow, providerHealthFromProbe, providerReadinessDecision, remediationForProvider, } from "./health.js";
+const SECRET_QUERY_NAME = /(?:api[-_]?key|authorization|password|secret|token)/iu;
+function safeEndpoint(value) {
+    if (typeof value !== 'string' || value.trim() === '')
+        return { value: null, host: null, valid: false };
+    try {
+        const url = new URL(value);
+        if (url.username || url.password)
+            return { value: null, host: null, valid: false };
+        for (const name of url.searchParams.keys())
+            if (SECRET_QUERY_NAME.test(name))
+                return { value: null, host: null, valid: false };
+        return { value: url.toString(), host: url.host, valid: true };
+    }
+    catch {
+        return { value: null, host: null, valid: false };
+    }
+}
+function authSource({ record, row, usable, environment }) {
+    const required = typeof row?.requiresKey === 'boolean' ? row.requiresKey : record?.chiaveObbligatoria === true;
+    if (!required)
+        return 'not-required';
+    if (row?.origineChiave === 'custodia')
+        return 'saved';
+    if (row?.origineChiave === 'ambiente' || usable)
+        return 'environment';
+    const state = String(environment?.state ?? '');
+    if (state === 'approved' || state === 'accepted')
+        return 'environment';
+    if (state === 'unanswered')
+        return 'environment-unanswered';
+    if (state === 'declined')
+        return 'environment-declined';
+    return 'missing';
+}
+export function createProviderControlPlane(deps) {
+    const healthByProvider = new Map();
+    const now = deps.now ?? Date.now;
+    function publicRows() { try {
+        return deps.publicProviders() ?? [];
+    }
+    catch {
+        return [];
+    } }
+    function records() {
+        return Object.values(deps.registry ?? {}).filter((record) => record?.destinazioneChat === true);
+    }
+    function rowFor(id) { return publicRows().find((row) => String(row?.id ?? '') === id) ?? {}; }
+    function recordFor(id) {
+        const record = deps.registry?.[id];
+        if (!record || record.destinazioneChat !== true)
+            throw Object.assign(new Error('PROVIDER_INVALID'), { code: 'PROVIDER_INVALID', provider: id });
+        return record;
+    }
+    function snapshot(id) {
+        const record = recordFor(id);
+        const row = rowFor(id);
+        let runtime = {};
+        try {
+            runtime = deps.runtimeFor(id) ?? {};
+        }
+        catch {
+            runtime = {};
+        }
+        let usableSecret = null;
+        try {
+            usableSecret = deps.keyFor(id) ?? null;
+        }
+        catch {
+            usableSecret = null;
+        }
+        const usable = Boolean(usableSecret);
+        let environment = null;
+        try {
+            environment = deps.environmentKey?.(id) ?? null;
+        }
+        catch {
+            environment = null;
+        }
+        const required = typeof row?.requiresKey === 'boolean' ? row.requiresKey : record.chiaveObbligatoria === true;
+        const source = authSource({ record, row, usable, environment });
+        const configured = !required || usable || row?.keyConfigured === true || source === 'environment' || source === 'saved';
+        const rawEndpoint = row?.endpoint ?? runtime?.endpoint ?? record?.baseUrl ?? null;
+        const safe = safeEndpoint(rawEndpoint);
+        const endpointless = record?.wire === 'acp';
+        const endpoint = {
+            value: safe.value,
+            host: safe.host,
+            valid: safe.valid || endpointless,
+            configured: row?.endpointConfigured === true || runtime?.endpointConfigured === true,
+            supportsCustom: row?.supportsEndpoint === true || record?.indirizzoModificabile === true,
+        };
+        const cooldown = providerCooldownFromRow(row);
+        const lastHealth = healthByProvider.get(id) ?? UNKNOWN_PROVIDER_HEALTH;
+        const execution = String(row?.execution ?? record?.esecuzione ?? 'unknown');
+        const runtimeConfigured = record?.wire === 'acp' ? execution === 'configurato' : true;
+        const base = {
+            id,
+            label: providerLabelText(id, String(row?.label ?? record?.etichetta ?? id)),
+            description: providerDescriptionText(id, String(record?.descrizione ?? '')),
+            auth: {
+                required,
+                type: String(record?.auth?.tipo ?? (required ? 'key' : 'none')),
+                source,
+                configured,
+                usable: required ? usable : true,
+                environmentVariable: typeof environment?.variable === 'string' ? environment.variable : null,
+            },
+            endpoint,
+            execution,
+            runtimeConfigured,
+            local: record?.wire === 'locale' || record?.catalogo?.fonte === 'runtime-locale' || /locale/u.test(String(record?.esecuzione ?? '')),
+            cloud: Boolean(record?.cloud),
+            supportsOAuth: row?.supportsOAuth === true || Boolean(record?.oauth),
+            cooldown,
+            lastHealth,
+        };
+        const remediation = remediationForProvider(base);
+        const decision = providerReadinessDecision(base);
+        return { ...base, remediation, ready: decision.ready };
+    }
+    return {
+        list() { return records().map((record) => snapshot(String(record.id))); },
+        get(id) { return snapshot(id); },
+        async probe(id, signal) {
+            recordFor(id);
+            const result = await deps.createProbe(signal).prova(id);
+            healthByProvider.set(id, providerHealthFromProbe(result, now()));
+            return snapshot(id);
+        },
+        invalidate(id) { recordFor(id); healthByProvider.delete(id); },
+        readiness(id) { return providerReadinessDecision(snapshot(id)); },
+    };
+}

package/dist/provider/environment-keys.js

@@ -0,0 +1,275 @@
+import { providerLabelText } from "./provider-text.js";
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { t } from "../i18n/index.js";
+import { missingKeyText } from "./missing-key.js";
+const RECORD_FILE = 'provider-consent.json';
+const HASH_KEY_FILE = 'provider-consent.key';
+const FINGERPRINT_PREFIX = 'hmac-sha256:';
+const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/u;
+const PROVIDER_ID = /^[a-z0-9][a-z0-9-]{0,63}$/u;
+/** The name rule of `diagnostics/redact.ts` (SECRET_KEY). A name that looks like a secret never reaches the store unapproved,
+ *  even when the registry that would name it is missing: the filter closes on what it cannot identify. */
+const SECRET_LOOKING_NAME = /^(?:.*(?:api[-_]?key|authorization|password|secret|token).*)$/iu;
+export function keyVariablesFor(registry, provider) {
+    const names = registry[provider]?.auth?.nomeVariabile;
+    return Array.isArray(names) ? names.filter(name => typeof name === 'string' && VARIABLE_NAME.test(name)) : [];
+}
+/** The credential store also reads `<first variable>_POOL`, a JSON list of keys. */
+export function poolVariableFor(registry, provider) {
+    const first = keyVariablesFor(registry, provider)[0];
+    return first ? `${first}_POOL` : null;
+}
+/** Every environment name through which the credential store can receive a provider key. */
+export function credentialVariableNames(registry) {
+    const names = new Set();
+    for (const provider of Object.keys(registry)) {
+        for (const name of keyVariablesFor(registry, provider))
+            names.add(name);
+        const pool = poolVariableFor(registry, provider);
+        if (pool)
+            names.add(pool);
+    }
+    return names;
+}
+/*
+ * ⛔ B1 slice 18, fix round — condition 8. On win32 environment names are case-insensitive: `process.env.OPENROUTER_API_KEY` finds a
+ *   variable spelled `OpenRouter_Api_Key`, but spreading `process.env` into a plain object keeps the spelling it was set with, and
+ *   the credential store reads the canonical name from that plain object. Measured by the coordinator: the approval was recorded
+ *   and the store saw no key. Every lookup here therefore folds case on win32, and the store receives the canonical name only.
+ */
+function foldName(name, platform) { return platform === 'win32' ? name.toUpperCase() : name; }
+/** The value of `name` as this platform resolves it: the exact spelling first, then (win32 only) any case variant. */
+function readVariable(env, name, platform) {
+    const exact = env[name];
+    if (typeof exact === 'string')
+        return exact;
+    if (platform !== 'win32')
+        return undefined;
+    const wanted = foldName(name, platform);
+    for (const [candidate, value] of Object.entries(env))
+        if (typeof value === 'string' && foldName(candidate, platform) === wanted)
+            return value;
+    return undefined;
+}
+/** The variable the credential store would read for this provider: the first non-empty one, trimmed, as the store does. */
+export function environmentKeyFor(env, registry, provider, platform = process.platform) {
+    for (const variable of keyVariablesFor(registry, provider)) {
+        const value = readVariable(env, variable, platform);
+        if (typeof value === 'string' && value.trim() !== '')
+            return { variable, value: value.trim() };
+    }
+    return null;
+}
+function emptyRecord() { return { version: 1, chosenProvider: null, environmentKeys: {} }; }
+function readRecord(file) {
+    if (!existsSync(file))
+        return emptyRecord();
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        if (parsed?.version !== 1 || !parsed.environmentKeys || typeof parsed.environmentKeys !== 'object' || Array.isArray(parsed.environmentKeys))
+            return emptyRecord();
+        const environmentKeys = {};
+        for (const [variable, row] of Object.entries(parsed.environmentKeys)) {
+            if (!VARIABLE_NAME.test(variable) || typeof row?.fingerprint !== 'string' || !row.fingerprint.startsWith(FINGERPRINT_PREFIX) || (row.answer !== 'yes' && row.answer !== 'no'))
+                continue;
+            environmentKeys[variable] = { fingerprint: row.fingerprint, answer: row.answer };
+        }
+        const chosenProvider = typeof parsed.chosenProvider === 'string' && PROVIDER_ID.test(parsed.chosenProvider) ? parsed.chosenProvider : null;
+        return { version: 1, chosenProvider, environmentKeys };
+    }
+    catch {
+        return emptyRecord();
+    }
+}
+function writeAtomically(file, text) {
+    const temporary = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    try {
+        writeFileSync(temporary, text, { encoding: 'utf8', mode: 0o600 });
+        renameSync(temporary, file);
+    }
+    catch (error) {
+        try {
+            if (existsSync(temporary))
+                unlinkSync(temporary);
+        }
+        catch { /* best effort */ }
+        throw Object.assign(new Error('PROVIDER_CONSENT_UNAVAILABLE'), { code: 'PROVIDER_CONSENT_UNAVAILABLE', cause: error });
+    }
+}
+export function createEnvironmentKeyConsent({ dataRoot, registry, env, platform = process.platform }) {
+    const recordFile = join(dataRoot, RECORD_FILE);
+    const hashKeyFile = join(dataRoot, HASH_KEY_FILE);
+    function readHashKey() {
+        try {
+            const text = readFileSync(hashKeyFile, 'utf8').trim();
+            return /^[a-f0-9]{64}$/u.test(text) ? Buffer.from(text, 'hex') : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    function hashKey(create) {
+        const existing = readHashKey();
+        if (existing || !create)
+            return existing;
+        mkdirSync(dataRoot, { recursive: true, mode: 0o700 });
+        const created = randomBytes(32);
+        writeAtomically(hashKeyFile, `${created.toString('hex')}\n`);
+        return created;
+    }
+    function fingerprint(value, key) { return `${FINGERPRINT_PREFIX}${createHmac('sha256', key).update(value, 'utf8').digest('hex')}`; }
+    function matches(expected, value, key) {
+        if (!key)
+            return false;
+        const actual = Buffer.from(fingerprint(value, key));
+        const wanted = Buffer.from(expected);
+        return actual.length === wanted.length && timingSafeEqual(actual, wanted);
+    }
+    function answerFor(variable, value, record = readRecord(recordFile), key = readHashKey()) {
+        const row = record.environmentKeys[variable];
+        return row && matches(row.fingerprint, value, key) ? row.answer : null;
+    }
+    function stateFor(provider) {
+        const found = environmentKeyFor(env, registry, provider, platform);
+        if (!found)
+            return null;
+        const answer = answerFor(found.variable, found.value);
+        return { provider, variable: found.variable, state: answer === 'yes' ? 'approved' : answer === 'no' ? 'declined' : 'unanswered' };
+    }
+    function answer(provider, value) {
+        if (value !== 'yes' && value !== 'no')
+            throw Object.assign(new Error('PROVIDER_CONSENT_ANSWER_INVALID'), { code: 'PROVIDER_CONSENT_ANSWER_INVALID' });
+        const found = environmentKeyFor(env, registry, provider, platform);
+        if (!found)
+            throw Object.assign(new Error('PROVIDER_ENVIRONMENT_KEY_NOT_FOUND'), { code: 'PROVIDER_ENVIRONMENT_KEY_NOT_FOUND' });
+        const key = hashKey(true);
+        const record = readRecord(recordFile);
+        record.environmentKeys[found.variable] = { fingerprint: fingerprint(found.value, key), answer: value };
+        mkdirSync(dataRoot, { recursive: true, mode: 0o700 });
+        writeAtomically(recordFile, `${JSON.stringify(record, null, 2)}\n`);
+        return { provider, variable: found.variable, state: value === 'yes' ? 'approved' : 'declined' };
+    }
+    function chosenProvider() { return readRecord(recordFile).chosenProvider; }
+    function chooseProvider(provider) {
+        if (typeof provider !== 'string' || !PROVIDER_ID.test(provider) || !registry[provider])
+            throw Object.assign(new Error('PROVIDER_INVALID'), { code: 'PROVIDER_INVALID' });
+        const record = readRecord(recordFile);
+        record.chosenProvider = provider;
+        mkdirSync(dataRoot, { recursive: true, mode: 0o700 });
+        writeAtomically(recordFile, `${JSON.stringify(record, null, 2)}\n`);
+    }
+    /**
+     * The environment the credential store may see in an interactive run: every provider-key variable is
+     * removed unless its CURRENT value was approved. Pool variables are never offered, so they never pass.
+     * Any other variable whose NAME looks like a secret is removed too. Endpoints and paths pass unchanged.
+     * ⛔ On win32 a provider-key or pool variable is recognised in ANY case, every spelling of it is removed, and an approved value
+     *   is put back under the registry's canonical name, the one the credential store reads.
+     */
+    function environmentForStore() {
+        const record = readRecord(recordFile);
+        const key = readHashKey();
+        const keyNames = new Set(Object.keys(registry).flatMap(provider => keyVariablesFor(registry, provider)));
+        const credentialNames = new Set([...credentialVariableNames(registry)].map(name => foldName(name, platform)));
+        const out = {};
+        for (const [name, value] of Object.entries(env)) {
+            if (credentialNames.has(foldName(name, platform)) || SECRET_LOOKING_NAME.test(name))
+                continue;
+            out[name] = value;
+        }
+        for (const name of keyNames) {
+            const value = readVariable(env, name, platform);
+            if (typeof value === 'string' && value.trim() !== '' && answerFor(name, value.trim(), record, key) === 'yes')
+                out[name] = value;
+        }
+        return out;
+    }
+    return { stateFor, answer, chosenProvider, chooseProvider, environmentForStore, files: { record: recordFile, hashKey: hashKeyFile } };
+}
+export function providerOfModel(model) {
+    const index = typeof model === 'string' ? model.indexOf(':') : -1;
+    return index > 0 ? model.slice(0, index) : null;
+}
+/** Where the key a run would use comes from, as the credential store sees it. Never the key itself. */
+export function describeKeyOrigin({ registry, provider, publicRow, storeEnv, mode, store }) {
+    const record = registry[provider];
+    if (!record)
+        return null;
+    const label = providerLabelText(provider, String(record.etichetta ?? provider));
+    const required = typeof publicRow?.requiresKey === 'boolean' ? publicRow.requiresKey : record.chiaveObbligatoria === true;
+    if (!required)
+        return { provider, label, required, origin: 'not-required', variable: null, askedFirst: false };
+    if (publicRow?.origineChiave === 'custodia')
+        return { provider, label, required, origin: 'keyring', variable: null, askedFirst: false, ...(store === 'memory' ? { store } : {}) };
+    if (publicRow?.origineChiave === 'ambiente')
+        return { provider, label, required, origin: 'environment', variable: environmentKeyFor(storeEnv, registry, provider)?.variable ?? null, askedFirst: mode === 'consent' };
+    return { provider, label, required, origin: 'none', variable: null, askedFirst: false };
+}
+export function keyOriginNotice(origin) {
+    /* R2 (E1, E13): the words come from the dictionary, and a key "saved" in the memory store is not said to be in the keyring. */
+    if (origin.origin === 'keyring')
+        return t(origin.store === 'memory' ? 'key.origin.saved.memory' : 'key.origin.saved.system', { provider: origin.label });
+    if (origin.origin === 'environment')
+        return t(origin.askedFirst ? 'key.origin.environment.approved' : 'key.origin.environment.unasked', { provider: origin.label, variable: origin.variable ?? t('key.origin.unknownVariable') });
+    return null;
+}
+/*
+ * ⭐ B1 slice 18, fix round — condition 3: WHO decides whether an environment key is used without asking. The ENTRIES do,
+ * explicitly: the interactive screen and `talos provider` ask (`consent`); `talos -p` and the one-shot commands that run a model
+ * (`research start`, `automation run`, `automation serve`, `session resume`) use it and state where it came from (`use`).
+ * The composition and the entry factories keep `consent` for a caller that forgets.
+ * ⛔ Every child the screen spawns carries `TALOS_ENVIRONMENT_KEYS=consent`. An entry honours the variable ONLY to close: the value
+ *   `consent` forces consent, and any other value, `use` included, is ignored. A variable can never open what an entry closed.
+ */
+export const ENVIRONMENT_KEYS_MARKER = 'TALOS_ENVIRONMENT_KEYS';
+export function environmentKeyModeForEntry(requested, env = process.env) {
+    return env[ENVIRONMENT_KEYS_MARKER] === 'consent' ? 'consent' : requested;
+}
+/** The environment a child of the interactive screen runs with: the screen's own, closed. */
+export function screenChildEnvironment(env = process.env) { return { ...env, [ENVIRONMENT_KEYS_MARKER]: 'consent' }; }
+/**
+ * For a one-shot command that runs a model, as `talos -p` does: the origin statement for that model's key, or null when the
+ * runtime cannot tell. With `refuseMissing`, a provider that needs a key it does not have is refused BEFORE anything is sent,
+ * with a coded error naming that provider (exit 11 through `exitCodeForError`).
+ */
+export function keyOriginForEntry(runtime, model, { refuseMissing }) {
+    const origin = keyOriginForRun(runtime, model);
+    if (!origin)
+        return null;
+    /* R2 (E8): the one missing-key sentence; the code is what lane E maps, never the text. */
+    if (refuseMissing && origin.required && origin.origin === 'none')
+        throw Object.assign(new Error(missingKeyText(origin.provider)), { code: 'PROVIDER_KEY_MISSING', provider: origin.provider });
+    return keyOriginNotice(origin);
+}
+/** States the origin the way the owner decided: one stderr line in text mode, a `warnings` entry in JSON. */
+export function stateKeyOrigin(io, outputFormat, notice) {
+    if (!notice)
+        return {};
+    if (outputFormat !== 'json')
+        io.writeErr(`${notice}\n`);
+    return { warnings: [notice] };
+}
+const ORIGINS = new WeakMap();
+/** Lets a run started through this runtime state its key origin without the runtime contract growing a field. */
+export function attachKeyOrigin(runtime, resolve) { ORIGINS.set(runtime, resolve); }
+/**
+ * ⛔ R0 (forensics B rows 2 and 5): a runtime that wraps another one (the M7-C supervisor, `26e46a339`) answers with the resolver of
+ *   the runtime it delegates to NOW, read at every lookup, so a restarted inner runtime keeps stating its key origin. Without it
+ *   the lookup on the wrapper found nothing: `talos -p` and `talos research start` stopped saying that an environment key was used
+ *   without asking, and the headless missing-key refusal lost its `talos provider set-key` remedy.
+ */
+export function forwardKeyOrigin(wrapper, delegate) {
+    attachKeyOrigin(wrapper, (model) => { const inner = delegate(); return inner && inner !== wrapper ? keyOriginForRun(inner, model) : null; });
+}
+export function keyOriginForRun(runtime, model) {
+    const resolve = ORIGINS.get(runtime);
+    if (!resolve)
+        return null;
+    try {
+        return resolve(model);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/provider/health.js

@@ -0,0 +1,110 @@
+import { t, tn } from "../i18n/index.js";
+import { missingKeyText } from "./missing-key.js";
+/*
+ * R2 (gate E1): the bench causes the kernel classifies (`provider-credential-store.mjs`, `PANCHINE_PROVIDER_MS`), in a person's
+ * words, from the dictionary (`key.bench.cause.<code>`). This is the one table: `tui/catalog-service.ts` had a second copy.
+ * A cause not in the table is shown as no cause, never guessed.
+ */
+const BENCH_CAUSE_CODES = new Set(['traffico', 'credenziale', 'credito', 'rete', 'timeout-fornitore', 'guasto-fornitore', 'flusso-interrotto']);
+export function benchCauseText(code) {
+    return typeof code === 'string' && BENCH_CAUSE_CODES.has(code) ? t(`key.bench.cause.${code}`) : null;
+}
+export const UNKNOWN_PROVIDER_HEALTH = Object.freeze({
+    state: 'unknown', detail: '', latencyMs: null, observedAt: null, httpStatus: null,
+});
+export function providerCooldownFromRow(row) {
+    const pool = Array.isArray(row?.pool) ? row.pool : [];
+    const benched = pool.filter(entry => entry?.stato === 'in-panchina');
+    const timed = benched.filter(entry => Number.isFinite(entry?.inPanchinaFino)).sort((a, b) => Number(a.inPanchinaFino) - Number(b.inPanchinaFino));
+    const first = timed[0] ?? benched[0] ?? null;
+    const cause = benchCauseText(first?.causa);
+    return {
+        active: benched.length > 0,
+        cause,
+        until: Number.isFinite(first?.inPanchinaFino) ? Number(first.inPanchinaFino) : null,
+        keys: pool.length,
+    };
+}
+export function providerHealthFromProbe(result, observedAt) {
+    const esito = String(result?.esito ?? '');
+    const code = typeof result?.codice === 'string' ? result.codice : null;
+    const state = esito === 'collegato' ? 'available' :
+        esito === 'non-autorizzato' ? 'auth-failed' :
+            esito === 'irraggiungibile' ? 'unreachable' :
+                esito === 'non-sondabile' ? 'unprobeable' :
+                    esito === 'non-provabile' ? (code === 'PROVIDER_RUNTIME_INVALID' || code === 'CATALOG_CONFIGURATION_REQUIRED' || code === 'PROVIDER_KEY_MISSING' ? 'unconfigured' : 'unprobeable') :
+                        esito === 'errore' ? 'error' : 'unknown';
+    return {
+        state,
+        detail: String(result?.motivo ?? esito),
+        latencyMs: Number.isFinite(result?.millisecondi) ? Number(result.millisecondi) : null,
+        observedAt: Number.isFinite(observedAt) ? observedAt : null,
+        httpStatus: Number.isInteger(result?.httpStatus) ? Number(result.httpStatus) : null,
+    };
+}
+/** "until when" as a person reads it: local HH:MM, with the local date in front when it is not today. */
+export function benchClock(until, now = Date.now()) {
+    const at = new Date(until);
+    const two = (n) => String(n).padStart(2, '0');
+    const time = `${two(at.getHours())}:${two(at.getMinutes())}`;
+    return at.toDateString() === new Date(now).toDateString() ? time : `${at.getFullYear()}-${two(at.getMonth() + 1)}-${two(at.getDate())} ${time}`;
+}
+/** "The OpenRouter key is benched until 15:04 (rate limit)". */
+export function benchedKeyText(label, bench, now = Date.now()) {
+    let state = tn('key.benched', bench.keys > 1 ? bench.keys : 1, { provider: label });
+    if (bench.until !== null)
+        state = t('key.benched.until', { state, time: benchClock(bench.until, now) });
+    if (bench.cause)
+        state = t('key.benched.because', { state, cause: bench.cause });
+    return state;
+}
+function benchedKeyRemedy(bench) { return t(bench.until !== null ? 'key.benched.remedy.until' : 'key.benched.remedy'); }
+/** The refusal of a send whose only keys are benched: the same sentence from the screen's readiness and from the session runtime. */
+export function benchedKeyRefusal(label, bench, now = Date.now()) {
+    return t('key.benched.refusal', { state: benchedKeyText(label, bench, now), provider: label, remedy: benchedKeyRemedy(bench) });
+}
+export function remediationForProvider(input) {
+    const provider = input.label;
+    if (input.auth.required && !input.auth.usable) {
+        if (input.cooldown.active) {
+            /* The state and the remedy; nothing was attempted yet, so the remediation does not say "nothing was sent". */
+            return { code: 'wait-or-add-key', message: t('key.benched.status', { state: benchedKeyText(provider, input.cooldown), remedy: benchedKeyRemedy(input.cooldown) }) };
+        }
+        /* R2 (E8 / Q-R2-7): the one missing-key sentence, the same on the screen, `-p`, `provider test` and `doctor`. */
+        return { code: 'add-key', message: missingKeyText(input.id) };
+    }
+    if (input.lastHealth.state === 'auth-failed')
+        return { code: 'replace-key', message: t('key.remedy.replaceKey', { provider }) };
+    if (!input.runtimeConfigured)
+        return { code: 'configure-provider', message: t('key.remedy.configureProvider', { provider }) };
+    if (!input.endpoint.valid)
+        return { code: 'configure-endpoint', message: t('key.remedy.configureEndpoint', { provider }) };
+    if (input.lastHealth.state === 'unreachable')
+        return { code: 'check-endpoint', message: t('key.remedy.checkEndpoint', { provider }) };
+    if (input.lastHealth.state === 'error')
+        return { code: 'retry', message: t('key.remedy.retry', { provider }) };
+    if (input.lastHealth.state === 'unconfigured')
+        return { code: 'configure-endpoint', message: t('key.remedy.completeConfiguration', { provider }) };
+    if (input.lastHealth.state === 'unprobeable')
+        return { code: 'inspect-provider', message: t('key.remedy.inspect', { provider }) };
+    return { code: 'none', message: '' };
+}
+export function providerReadinessDecision(input) {
+    const remediation = remediationForProvider(input);
+    if (input.auth.required && !input.auth.usable) {
+        if (input.cooldown.active)
+            return { ready: false, provider: input.id, code: 'PROVIDER_KEY_BENCHED', message: benchedKeyRefusal(input.label, input.cooldown), remediation };
+        return { ready: false, provider: input.id, code: 'PROVIDER_KEY_MISSING', message: remediation.message, remediation };
+    }
+    if (input.lastHealth.state === 'auth-failed')
+        return { ready: false, provider: input.id, code: 'PROVIDER_AUTH_FAILED', message: remediation.message, remediation };
+    if (!input.runtimeConfigured)
+        return { ready: false, provider: input.id, code: 'PROVIDER_NOT_CONFIGURED', message: remediation.message, remediation };
+    if (!input.endpoint.valid)
+        return { ready: false, provider: input.id, code: 'PROVIDER_ENDPOINT_INVALID', message: remediation.message, remediation };
+    if (input.lastHealth.state === 'unreachable')
+        return { ready: false, provider: input.id, code: 'PROVIDER_UNREACHABLE', message: remediation.message, remediation };
+    if (input.lastHealth.state === 'error' || input.lastHealth.state === 'unconfigured')
+        return { ready: false, provider: input.id, code: 'PROVIDER_HEALTH_ERROR', message: remediation.message, remediation };
+    return { ready: true, provider: input.id, remediation };
+}

package/dist/provider/missing-key.js

@@ -0,0 +1,48 @@
+/*
+ * R2 CONTRACT (owner: lane K; stub written by the coordinator so parallel lanes compile). The ONE missing-key sentence,
+ * used verbatim by the TUI refusal, `-p` (text and JSON message), `provider test` and `doctor` (Q-R2-7, gate E8).
+ * Lanes other than K only CALL `missingKeyText`; lane K owns the implementation and may not change the signature.
+ *
+ * ⛔ Where the label and the variable come from, measured: the kernel's registry (`harness-ui/src/provider-registry.mjs`,
+ *   `REGISTRO_FORNITORI[id].etichetta` and `.auth.nomeVariabile`), the table every path already reads. The CLI's
+ *   `ProviderDefinition.env` (`provider/store.ts`) is used by no production path. The registry is a kernel module loaded
+ *   asynchronously from the repo root, so the composition hands it here once (`useProviderRegistry`) and this function stays
+ *   synchronous. The variable is the FIRST one (gate E8): `kimi` names MOONSHOT_API_KEY, the one the store reads first.
+ * ⛔ A provider the registry does not name gets the sentence without a variable, never an invented one.
+ */
+import { providerLabelText } from "./provider-text.js";
+import { t } from "../i18n/index.js";
+import { keyVariablesFor } from "./environment-keys.js";
+let registry = {};
+/** Called by the composition with the kernel's registry; the last composition in the process wins (the table is the same). */
+export function useProviderRegistry(value) { registry = value && typeof value === 'object' ? value : {}; }
+/** The provider id for `ref`, which is an id or (for a caller that only holds a row's label) a label. */
+function providerIdOf(ref) {
+    if (Object.hasOwn(registry, ref))
+        return ref;
+    for (const [id, record] of Object.entries(registry))
+        if (record?.etichetta === ref || providerLabelText(id, '') === ref)
+            return id;
+    return null;
+}
+/**
+ * The label a person reads for `ref` (an id or a label); `fallback` (or `ref`) when the registry does not know it.
+ * ⛔ Open (gate §1.4, E4 "provider id for labels"): four registry labels carry Italian (`esterno`, `local`, `zai-anthropic`,
+ *   `minimax-anthropic`). They are NOT replaced here alone: the provider overlay takes its label from `provider/control-plane.ts`,
+ *   and an English label in this sentence under an Italian overlay title was measured in one frame. This function is the seam
+ *   for that mapping once every surface reads it.
+ */
+export function providerLabel(ref, fallback = ref) {
+    const id = providerIdOf(ref);
+    if (!id)
+        return fallback;
+    return providerLabelText(id, String(registry[id]?.etichetta ?? id));
+}
+export function missingKeyText(providerId) {
+    const id = providerIdOf(providerId);
+    if (!id)
+        return t('key.missing.noEnv', { provider: providerId, id: providerId });
+    const provider = providerLabel(id);
+    const env = keyVariablesFor(registry, id)[0];
+    return env ? t('key.missing', { provider, env, id }) : t('key.missing.noEnv', { provider, id });
+}