talos-code 0.0.1 → 0.1.0

package/dist/commands/extensions-cli.js

@@ -0,0 +1,207 @@
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { assertNoUnknownOptions, writeValue } from "./context.js";
+import { installExtension, removeInstalledExtension } from "../extensions/installer.js";
+import { createTrustAuthority } from "../security/trust-authority.js";
+import { createMcpFacade } from "../services/mcp-facade.js";
+import { createHookFacade } from "../services/hook-facade.js";
+import { createPluginFacade } from "../services/plugin-facade.js";
+import { createWorkflowCatalog } from "../services/workflow-catalog.js";
+import { createWorkflowCenterModel, renderWorkflowCenterLines } from "../tui/overlays/workflow-center.js";
+function id(v) { if (!v || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,120}$/u.test(v) || v.includes('..'))
+    throw new Error('EXTENSION_ID_INVALID'); return v; }
+function authority(ctx) { return createTrustAuthority({ projectRoot: ctx.projectRoot, trustRoot: ctx.paths.trust.projects }); }
+async function removeMirror(root, value) { const clean = id(value); await rm(join(root, `${clean}.json`), { force: true }); }
+async function mirrorRoot(ctx, kind) { const roots = await authority(ctx).compatibilityRoots(); return kind === 'hook' ? roots.hooks : kind === 'mcp' ? roots.mcp : roots.plugins; }
+export async function runMcpCommand(ctx, args0, facade = createMcpFacade({ projectRoot: ctx.projectRoot, repoRoot: ctx.repoRoot, paths: ctx.paths })) {
+    const a = [...args0], op = a.shift() ?? 'list';
+    if (op === 'list') {
+        assertNoUnknownOptions(a);
+        writeValue(ctx, await facade.list());
+        return 0;
+    }
+    const sid = id(a.shift());
+    assertNoUnknownOptions(a);
+    if (op === 'trust') {
+        const result = await facade.trust(sid);
+        writeValue(ctx, { ok: true, id: sid, changed: result.changed }, result.changed ? 'Trusted MCP ' + sid + '\n' : 'MCP ' + sid + ' already trusted by the project authority\n');
+        return 0;
+    }
+    if (op === 'untrust') {
+        const result = await facade.untrust(sid);
+        writeValue(ctx, { ok: true, id: sid, changed: result.changed }, 'Untrusted MCP ' + sid + '\n');
+        return 0;
+    }
+    if (op === 'test') {
+        const result = await facade.probe(sid);
+        const ok = result.health.state === 'healthy' || result.health.state === 'degraded';
+        const output = {
+            ok, id: sid, health: result.health, server: result.server, protocol: result.protocol, capabilities: result.capabilities,
+            tools: result.permission.effectiveTools, missingAllowlistedTools: result.permission.missingAllowlistedTools,
+            trust: result.trust, permission: result.permission, logs: result.logs, error: ok ? null : result.health.message
+        };
+        writeValue(ctx, output);
+        return ok ? 0 : 15;
+    }
+    throw new Error('Unsupported mcp operation: ' + op);
+}
+export async function runHookCommand(ctx, args0, facade = createHookFacade({ projectRoot: ctx.projectRoot, repoRoot: ctx.repoRoot, paths: ctx.paths })) {
+    const a = [...args0], op = a.shift() ?? 'list';
+    if (op === 'list') {
+        assertNoUnknownOptions(a);
+        if (a.length)
+            throw new Error('HOOK_LIST_TAKES_NO_ARGUMENTS');
+        writeValue(ctx, await facade.list());
+        return 0;
+    }
+    const hid = id(a.shift());
+    if (op === 'trust') {
+        assertNoUnknownOptions(a);
+        if (a.length)
+            throw new Error('HOOK_TRUST_TAKES_ONE_ID');
+        const result = await facade.trust(hid);
+        writeValue(ctx, { ok: true, id: hid, changed: result.changed }, result.changed ? 'Trusted hook ' + hid + '\n' : 'Hook ' + hid + ' already trusted by the project authority\n');
+        return 0;
+    }
+    if (op === 'untrust') {
+        assertNoUnknownOptions(a);
+        if (a.length)
+            throw new Error('HOOK_UNTRUST_TAKES_ONE_ID');
+        const result = await facade.untrust(hid);
+        writeValue(ctx, { ok: true, id: hid, changed: result.changed }, 'Untrusted hook ' + hid + '\n');
+        return 0;
+    }
+    if (op === 'dry-run') {
+        const eventType = a.shift();
+        if (!eventType)
+            throw new Error('HOOK_EVENT_REQUIRED');
+        const action = a.length ? a.join(' ') : null;
+        const result = await facade.dryRun(hid, { eventType, action });
+        writeValue(ctx, { ok: true, id: hid, ...result }, 'Executed hook ' + hid + ' with a synthetic ' + eventType + ' event through the real hook process path.\n');
+        return 0;
+    }
+    if (op === 'history') {
+        const rawLimit = a.shift();
+        assertNoUnknownOptions(a);
+        if (a.length)
+            throw new Error('HOOK_HISTORY_ARGUMENTS_INVALID');
+        let limit;
+        if (rawLimit !== undefined) {
+            limit = Number(rawLimit);
+            if (!Number.isSafeInteger(limit) || limit < 1 || limit > 50)
+                throw new Error('HOOK_HISTORY_LIMIT_INVALID');
+        }
+        const rows = await facade.history(hid, limit === undefined ? {} : { limit });
+        writeValue(ctx, rows);
+        return 0;
+    }
+    if (op === 'quarantine') {
+        const reason = a.length ? a.join(' ') : null;
+        const result = await facade.quarantine(hid, reason);
+        writeValue(ctx, { ok: true, id: hid, changed: result.changed, quarantine: result.record }, 'Quarantined hook ' + hid + '. It remains denied until quarantine is explicitly released, and release does not restore trust.\n');
+        return 0;
+    }
+    if (op === 'release' || op === 'release-quarantine') {
+        assertNoUnknownOptions(a);
+        if (a.length)
+            throw new Error('HOOK_RELEASE_TAKES_ONE_ID');
+        const result = await facade.releaseQuarantine(hid);
+        writeValue(ctx, { ok: true, id: hid, changed: result.changed }, 'Released hook quarantine for ' + hid + '. The hook remains untrusted until explicitly trusted again.\n');
+        return 0;
+    }
+    throw new Error('Unsupported hook operation: ' + op);
+}
+export async function runPluginCommand(ctx, args0, facade = createPluginFacade({ projectRoot: ctx.projectRoot, repoRoot: ctx.repoRoot, paths: ctx.paths })) {
+    const a = [...args0], op = a.shift() ?? 'list';
+    if (op === 'install') {
+        const source = a.shift();
+        if (!source)
+            throw new Error('PLUGIN_SOURCE_REQUIRED');
+        assertNoUnknownOptions(a);
+        const result = await installExtension({ source, projectRoot: ctx.projectRoot });
+        writeValue(ctx, result, 'Installed ' + result.id + ' ' + result.version + '; project trust must cover the new package before it can run\n');
+        return 0;
+    }
+    if (op === 'remove') {
+        const pid = id(a.shift());
+        assertNoUnknownOptions(a);
+        const result = await removeInstalledExtension({ projectRoot: ctx.projectRoot, id: pid });
+        const trust = authority(ctx);
+        await trust.untrustScope({ kind: 'plugin', id: pid });
+        await removeMirror(await mirrorRoot(ctx, 'plugin'), pid);
+        writeValue(ctx, result, 'Removed ' + pid + '\n');
+        return 0;
+    }
+    if (op === 'list') {
+        assertNoUnknownOptions(a);
+        if (a.length)
+            throw new Error('PLUGIN_LIST_TAKES_NO_ARGUMENTS');
+        writeValue(ctx, await facade.list());
+        return 0;
+    }
+    const pid = id(a.shift());
+    if (op === 'trust') {
+        assertNoUnknownOptions(a);
+        if (a.length)
+            throw new Error('PLUGIN_TRUST_TAKES_ONE_ID');
+        const result = await facade.trust(pid);
+        writeValue(ctx, { ok: true, id: pid, guard: result.guard, changed: result.changed }, result.changed ? 'Trusted plugin ' + pid + '\n' : 'Plugin ' + pid + ' already trusted by the project authority\n');
+        return 0;
+    }
+    if (op === 'untrust') {
+        assertNoUnknownOptions(a);
+        if (a.length)
+            throw new Error('PLUGIN_UNTRUST_TAKES_ONE_ID');
+        const result = await facade.untrust(pid);
+        writeValue(ctx, { ok: true, id: pid, changed: result.changed }, 'Untrusted plugin ' + pid + '\n');
+        return 0;
+    }
+    if (op === 'quarantine') {
+        const reason = a.length ? a.join(' ') : null;
+        const result = await facade.quarantine(pid, reason);
+        writeValue(ctx, { ok: true, id: pid, changed: result.changed, quarantine: result.record }, 'Quarantined plugin ' + pid + '. It cannot regain trust until quarantine is explicitly released.\n');
+        return 0;
+    }
+    if (op === 'release' || op === 'release-quarantine') {
+        assertNoUnknownOptions(a);
+        if (a.length)
+            throw new Error('PLUGIN_RELEASE_TAKES_ONE_ID');
+        const result = await facade.releaseQuarantine(pid);
+        writeValue(ctx, { ok: true, id: pid, changed: result.changed }, 'Released plugin quarantine for ' + pid + '. The plugin remains untrusted until explicitly trusted again.\n');
+        return 0;
+    }
+    throw new Error('Unsupported plugin operation: ' + op);
+}
+export async function runCustomCommand(ctx, args0, catalog = createWorkflowCatalog({ projectRoot: ctx.projectRoot, repoRoot: ctx.repoRoot, paths: ctx.paths })) {
+    const a = [...args0], op = a.shift() ?? 'list';
+    if (op === 'list') {
+        assertNoUnknownOptions(a);
+        if (a.length)
+            throw new Error('COMMAND_LIST_TAKES_NO_ARGUMENTS');
+        const rows = await catalog.list();
+        const human = renderWorkflowCenterLines(createWorkflowCenterModel(rows, 0)).join('\n') + '\n';
+        writeValue(ctx, rows, human);
+        return 0;
+    }
+    if (op === 'show') {
+        const selector = a.shift();
+        if (!selector)
+            throw new Error('COMMAND_NAME_REQUIRED');
+        assertNoUnknownOptions(a);
+        if (a.length)
+            throw new Error('COMMAND_SHOW_TAKES_ONE_NAME');
+        const row = await catalog.show(selector);
+        const human = renderWorkflowCenterLines(createWorkflowCenterModel([row], 0)).join('\n') + '\n';
+        writeValue(ctx, row, human);
+        return 0;
+    }
+    if (op === 'run') {
+        const selector = a.shift();
+        if (!selector)
+            throw new Error('COMMAND_NAME_REQUIRED');
+        const result = await catalog.run(selector, a);
+        writeValue(ctx, result, result.prompt.endsWith('\n') ? result.prompt : result.prompt + '\n');
+        return 0;
+    }
+    throw new Error('Unsupported command operation: ' + op);
+}

package/dist/commands/project-cli.js

@@ -0,0 +1,74 @@
+import { assertNoUnknownOptions, takeFlag, writeValue } from "./context.js";
+import { createTrustAuthority } from "../security/trust-authority.js";
+import { t } from "../i18n/index.js";
+import { inertProjectTrustText } from "../tui/project-trust-prompt.js";
+function publicSnapshot(value, folder) {
+    return {
+        trusted: value.trusted, reason: value.reason, project: value.workspace.canonicalRoot, identity: value.workspace.identityHash,
+        nestedRepository: value.workspace.nestedRepository, nestedRepositories: value.nestedRepositories.map(entry => entry.relativePath),
+        resourceCount: value.resources.filter(row => row.current).length,
+        storeSchema: value.storeSchema, migrationRequired: value.migrationRequired, rollbackAvailable: value.rollbackAvailable,
+        resources: value.resources.map(row => ({ kind: row.kind, id: row.id, path: row.relativePath, state: row.state })),
+        /* R4 (gate E2): the folder decision, apart from the per-file snapshot. */
+        folder: { decided: folder.decided, source: folder.source, path: folder.path, sessionOnly: folder.sessionOnly }
+    };
+}
+/** `deps.homeDir` exists for tests: which folder counts as the home folder (default: the user's home). */
+export async function runProjectCommand(ctx, args0, deps = {}) {
+    const args = [...args0];
+    const operation = args.shift() ?? 'status';
+    const includeNested = operation === 'trust' || operation === 'migrate-trust' ? takeFlag(args, '--include-nested') : false;
+    assertNoUnknownOptions(args);
+    if (args.length)
+        throw new Error('PROJECT_COMMAND_ARGUMENT_INVALID');
+    const authority = createTrustAuthority({ projectRoot: ctx.projectRoot, trustRoot: ctx.paths.trust.projects, ...(deps.homeDir ? { homeDir: deps.homeDir } : {}) });
+    const view = async (snapshot) => publicSnapshot(snapshot, await authority.folderDecision(snapshot));
+    if (operation === 'status') {
+        writeValue(ctx, await view(await authority.inspect()));
+        return 0;
+    }
+    if (operation === 'trust') {
+        const before = await authority.inspect();
+        const folder = await authority.folderDecision(before);
+        /* Q-R4-1: the home folder and a drive root are never saved. Their project files still follow the snapshot rule. */
+        if (folder.sessionOnly) {
+            const sessionLine = t('firstrun.project.sessionOnly', { path: inertProjectTrustText(before.workspace.canonicalRoot) }) + '\n';
+            /* Q-R4-17: its files are trusted only by the interactive question, for that session; this command saves nothing. */
+            writeValue(ctx, publicSnapshot(before, folder), sessionLine);
+            return 0;
+        }
+        if (before.trusted && folder.decided) {
+            writeValue(ctx, publicSnapshot(before, folder), before.migrationRequired ? `Project already trusted; run talos project migrate-trust to migrate the legacy store explicitly\n` : `Project already trusted ${before.workspace.canonicalRoot}\n`);
+            return 0;
+        }
+        const verified = await authority.trustProject({ expected: before, includeNested });
+        writeValue(ctx, await view(verified), `Trusted project ${verified.workspace.canonicalRoot}\n`);
+        return 0;
+    }
+    if (operation === 'revoke') {
+        const revoked = await authority.revokeProject();
+        writeValue(ctx, await view(revoked), `Revoked project ${revoked.workspace.canonicalRoot}\n`);
+        return 0;
+    }
+    if (operation === 'migrate-trust') {
+        const before = await authority.inspect();
+        if (before.storeSchema !== 'v1') {
+            writeValue(ctx, await view(before), before.storeSchema === 'v2' ? 'Project trust store is already v2; no migration was performed\n' : 'No legacy trust record to migrate\n');
+            return 0;
+        }
+        const migrated = await authority.migrateLegacy({ includeNested });
+        writeValue(ctx, await view(migrated), `Project trust store migrated to v2; rollback backup: ${await authority.migrationBackupPath()}\n`);
+        return 0;
+    }
+    if (operation === 'rollback-trust-migration') {
+        const before = await authority.inspect();
+        if (!before.rollbackAvailable) {
+            writeValue(ctx, await view(before), 'No migration rollback backup is available\n');
+            return 0;
+        }
+        const rolledBack = await authority.rollbackMigration();
+        writeValue(ctx, await view(rolledBack), `Rolled project trust store back to legacy v1\n`);
+        return 0;
+    }
+    throw new Error(`Unsupported project operation: ${operation}`);
+}

package/dist/commands/project-commands.js

@@ -0,0 +1,143 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const NAME = /^[a-z0-9][a-z0-9-]{0,63}$/u;
+const MAX_FILE_BYTES = 65_536;
+export const WORKFLOW_MAX_STEPS = 64;
+export const WORKFLOW_MAX_TEXT_BYTES = 16_384;
+function fail(code, message = code) { throw Object.assign(new Error(message), { code }); }
+function textBytes(value) { return Buffer.byteLength(value, 'utf8'); }
+function assertBoundedText(value, code, { allowEmpty = false } = {}) {
+    if (typeof value !== 'string' || (!allowEmpty && !value.trim()) || textBytes(value) > WORKFLOW_MAX_TEXT_BYTES)
+        fail(code);
+    return value;
+}
+function exactKeys(value, allowed, code) {
+    if (Object.keys(value).some(key => !allowed.includes(key)))
+        fail(code);
+}
+function workflowSteps(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        fail('WORKFLOW_STEPS_INVALID');
+    }
+    if (!Array.isArray(value) || value.length === 0)
+        fail('WORKFLOW_STEPS_INVALID');
+    if (value.length > WORKFLOW_MAX_STEPS)
+        fail('WORKFLOW_TOO_MANY_STEPS');
+    const steps = [];
+    for (const entry of value) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            fail('WORKFLOW_STEP_INVALID');
+        const row = entry;
+        if (row.type === 'prompt') {
+            exactKeys(row, ['type', 'template'], 'WORKFLOW_STEP_UNKNOWN_KEY');
+            steps.push({ type: 'prompt', template: assertBoundedText(row.template, 'WORKFLOW_PROMPT_INVALID') });
+            continue;
+        }
+        if (row.type === 'skill') {
+            exactKeys(row, ['type', 'name'], 'WORKFLOW_STEP_UNKNOWN_KEY');
+            const name = assertBoundedText(row.name, 'WORKFLOW_SKILL_INVALID');
+            if (!NAME.test(name))
+                fail('WORKFLOW_SKILL_INVALID');
+            steps.push({ type: 'skill', name });
+            continue;
+        }
+        if (row.type === 'command') {
+            exactKeys(row, ['type', 'name', 'args'], 'WORKFLOW_STEP_UNKNOWN_KEY');
+            const name = assertBoundedText(row.name, 'WORKFLOW_COMMAND_INVALID');
+            if (!NAME.test(name))
+                fail('WORKFLOW_COMMAND_INVALID');
+            const args = row.args ?? [];
+            if (!Array.isArray(args) || args.length > WORKFLOW_MAX_STEPS || !args.every(arg => typeof arg === 'string' && textBytes(arg) <= WORKFLOW_MAX_TEXT_BYTES))
+                fail('WORKFLOW_COMMAND_ARGS_INVALID');
+            steps.push({ type: 'command', name, args: [...args] });
+            continue;
+        }
+        fail('WORKFLOW_STEP_TYPE_INVALID');
+    }
+    return steps;
+}
+function parse(text, file) {
+    if (Buffer.byteLength(text) > MAX_FILE_BYTES)
+        throw new Error('COMMAND_TOO_LARGE');
+    const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/u.exec(text);
+    if (!m)
+        throw new Error(`COMMAND_FRONT_MATTER_INVALID:${file}`);
+    const meta = {};
+    for (const line of m[1].split(/\r?\n/u)) {
+        if (!line.trim())
+            continue;
+        const mm = /^([A-Za-z]+):\s*(.*)$/u.exec(line);
+        if (!mm)
+            throw new Error('COMMAND_FRONT_MATTER_INVALID');
+        if (!['name', 'description', 'arguments', 'kind', 'steps'].includes(mm[1]))
+            throw new Error('COMMAND_FIELD_UNKNOWN');
+        if (Object.hasOwn(meta, mm[1]))
+            throw new Error('COMMAND_FIELD_DUPLICATE');
+        meta[mm[1]] = mm[2].replace(/^['"]|['"]$/gu, '');
+    }
+    if (!meta.name || !NAME.test(meta.name) || !meta.description)
+        throw new Error('COMMAND_FRONT_MATTER_INVALID');
+    const kind = meta.kind ?? 'command';
+    if (kind !== 'command' && kind !== 'workflow')
+        fail('WORKFLOW_KIND_INVALID');
+    const body = m[2].trim();
+    if (kind === 'command') {
+        if (meta.steps !== undefined)
+            fail('WORKFLOW_STEPS_FORBIDDEN');
+        return { name: meta.name, description: meta.description, arguments: meta.arguments ?? '', body, file, kind: 'command', steps: [] };
+    }
+    if (meta.steps === undefined)
+        fail('WORKFLOW_STEPS_REQUIRED');
+    if (body)
+        fail('WORKFLOW_BODY_FORBIDDEN');
+    return { name: meta.name, description: meta.description, arguments: meta.arguments ?? '', body: '', file, kind: 'workflow', steps: workflowSteps(meta.steps) };
+}
+export async function loadCommandFile(file) { return parse(await readFile(file, 'utf8'), file); }
+async function markdownFiles(root) {
+    const out = [];
+    async function walk(dir) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (e) {
+            if (e?.code === 'ENOENT')
+                return;
+            throw e;
+        }
+        for (const e of entries) {
+            const p = join(dir, e.name);
+            if (e.isDirectory())
+                await walk(p);
+            else if (e.isFile() && e.name.endsWith('.md'))
+                out.push(p);
+        }
+    }
+    await walk(root);
+    return out.sort();
+}
+export async function loadProjectCommands(root) {
+    const files = await markdownFiles(join(root, '.talos-cli', 'commands'));
+    const out = [];
+    const names = new Set();
+    for (const f of files) {
+        const c = await loadCommandFile(f);
+        if (names.has(c.name))
+            throw new Error('COMMAND_NAME_DUPLICATE');
+        names.add(c.name);
+        out.push(c);
+    }
+    return out;
+}
+export function expandCommand(c, vars) {
+    return c.body.replace(/\{\{([a-zA-Z0-9_-]+)\}\}/gu, (_m, n) => {
+        if (!Object.hasOwn(vars, n))
+            throw new Error(`COMMAND_VARIABLE_UNKNOWN:${n}`);
+        return vars[n];
+    });
+}
+export const renderProjectCommand = expandCommand;

package/dist/commands/provider-cli.js

@@ -0,0 +1,185 @@
+import { kernelProbeDetail } from "../i18n/kernel-map.js";
+import { assertNoUnknownOptions, takeFlag, takeOption, writeValue } from "./context.js";
+import { REASONING_EFFORTS } from "../config/types.js";
+import { importTalosModule } from "../runtime/repo.js";
+import { createEnvironmentKeyConsent, providerOfModel } from "../provider/environment-keys.js";
+import { t } from "../i18n/index.js";
+/*
+ * B1 slice 18 — the command line follows the rules of `/provider`: the store sees an environment key only after it
+ * was approved (`talos provider env-key <id> --use`; nothing said means No), and `set-key` tests the key against its
+ * own provider and saves it only when the test passes. The key is read through the hidden prompt, never from argv.
+ */
+async function runtimeContext(ctx) { return ctx.createRuntimeContext({ projectRoot: ctx.projectRoot, paths: ctx.paths, repoRoot: ctx.repoRoot, model: ctx.invocation.model ?? 'openai:gpt-5-mini', environmentKeys: 'consent' }); }
+function environmentKeyOf(row) { return row && row.environmentVariable ? { variable: String(row.environmentVariable), state: row.keySource === 'environment' ? 'approved' : row.keySource === 'environment-declined' ? 'declined' : 'unanswered' } : null; }
+export async function runProviderCommand(ctx, args0) { const args = [...args0]; const op = args.shift() ?? 'list'; const rc = await runtimeContext(ctx); const store = rc.providerStore; const catalog = rc.tuiCatalog; if (op === 'list') {
+    assertNoUnknownOptions(args);
+    if (typeof rc.providerControlPlane?.list === 'function') {
+        writeValue(ctx, rc.providerControlPlane.list());
+        return 0;
+    }
+    const rows = store.listPublic();
+    let providers = [];
+    try {
+        providers = await catalog?.listProviders?.() ?? [];
+    }
+    catch {
+        providers = [];
+    }
+    writeValue(ctx, rows.map((row) => ({ ...row, environmentKey: environmentKeyOf(providers.find((p) => p.id === row?.id)) })));
+    return 0;
+} const id = args.shift(); if (!id)
+    throw new Error('PROVIDER_REQUIRED'); if (op === 'set-key') {
+    assertNoUnknownOptions(args);
+    if (!ctx.io.readSecret)
+        throw new Error('SECRET_INPUT_REQUIRES_TTY');
+    if (typeof catalog?.setProviderKey !== 'function')
+        throw Object.assign(new Error('PROVIDER_KEY_TEST_UNAVAILABLE'), { code: 'PROVIDER_KEY_TEST_UNAVAILABLE' }); /* a one-token key test is stated before the key is read, so before anything is sent; nothing further is asked */
+    const notice = typeof catalog.keyTestNotice === 'function' ? catalog.keyTestNotice(id) : null;
+    if (notice)
+        ctx.io.writeErr(`${notice}\n`);
+    let secret = await ctx.io.readSecret(`Key for ${id}: `);
+    let result;
+    try {
+        result = await catalog.setProviderKey(id, secret);
+    }
+    finally {
+        secret = '';
+    }
+    const saved = result.saved === true;
+    writeValue(ctx, { ok: saved, provider: id, outcome: result.outcome, httpStatus: result.httpStatus, saved }, `${result.message} ${saved ? 'Saved.' : 'The key was not saved.'}\n`);
+    return saved ? 0 : 11;
+} if (op === 'env-key') {
+    const use = takeFlag(args, '--use');
+    const decline = takeFlag(args, '--decline');
+    assertNoUnknownOptions(args);
+    if (use && decline)
+        throw new Error('Use either --use or --decline');
+    const row = (await catalog.listProviders()).find((p) => p.id === id);
+    if (!row)
+        throw Object.assign(new Error('PROVIDER_INVALID'), { code: 'PROVIDER_INVALID' });
+    const answering = use || decline;
+    if (answering && row.environmentVariable)
+        await catalog.answerEnvironmentKey(id, use ? 'yes' : 'no');
+    const after = answering ? (await catalog.listProviders()).find((p) => p.id === id) : row;
+    const state = environmentKeyOf(after);
+    if (!state) {
+        writeValue(ctx, { ok: !answering, provider: id, environmentKey: null }, `No key for ${after?.label ?? id} was found in the environment.\n`);
+        return answering ? 2 : 0;
+    }
+    writeValue(ctx, { ok: true, provider: id, environmentKey: state }, `${state.variable}: ${state.state === 'approved' ? 'used for ' + after.label : state.state === 'declined' ? 'declined, not used' : 'not used until approved (talos provider env-key ' + id + ' --use)'}\n`);
+    return 0;
+} if (op === 'remove-key') {
+    assertNoUnknownOptions(args);
+    store.clearKey(id);
+    rc.providerControlPlane?.invalidate?.(id);
+    writeValue(ctx, { ok: true, provider: id }, `Removed key for ${id}\n`);
+    return 0;
+} if (op === 'configure') {
+    const endpoint = takeOption(args, '--endpoint');
+    const timeoutRaw = takeOption(args, '--timeout');
+    assertNoUnknownOptions(args);
+    const current = store.getRuntime(id) ?? {};
+    const timeoutSeconds = timeoutRaw === undefined ? current.timeoutSeconds : Number(timeoutRaw);
+    if (timeoutRaw !== undefined && (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 5 || timeoutSeconds > 300))
+        throw new Error('PROVIDER_TIMEOUT_INVALID');
+    if (endpoint === undefined && timeoutRaw === undefined)
+        throw new Error('PROVIDER_CONFIG_REQUIRED');
+    store.setRuntime(id, { ...current, ...(endpoint !== undefined ? { endpoint } : {}), ...(timeoutSeconds !== undefined ? { timeoutSeconds } : {}) });
+    rc.providerControlPlane?.invalidate?.(id);
+    writeValue(ctx, { ok: true, provider: id, runtime: store.getRuntime(id) }, `Configured ${id}\n`);
+    return 0;
+} if (op === 'test') {
+    assertNoUnknownOptions(args); /* M5-A/M5-C: ordinary health testing never opts into token generation, and remediation is the control-plane decision. */
+    if (typeof rc.providerControlPlane?.probe === 'function') {
+        const profile = await rc.providerControlPlane.probe(id);
+        const health = profile.lastHealth ?? {};
+        const latency = Number.isFinite(health.latencyMs) ? ` · ${health.latencyMs} ms` : ''; /* R2 (E8 / Q-R2-7): a missing key is the one sentence, as a line of its own; the probe's free-text reason (the kernel's, Italian) is mapped by the remediation code and not printed. */
+        const missingKey = profile.remediation?.code === 'add-key';
+        const remedy = missingKey ? `${profile.remediation.message}\n` : profile.remediation?.code && profile.remediation.code !== 'none' ? `Remedy: ${profile.remediation.message}\n` : ''; /* R4 Q-R4-16 (a): the kernel's sentence in English by a pinned template, or not printed. */
+        const mapped = health.detail && !missingKey ? kernelProbeDetail(String(health.detail), { label: String(profile.label ?? id) }) : null;
+        const detail = mapped ? `${mapped}\n` : '';
+        writeValue(ctx, missingKey ? { ...profile, code: 'PROVIDER_KEY_MISSING' } : profile, `${profile.label ?? id}: ${health.state ?? 'unknown'}${latency}\n${detail}${remedy}`);
+        return health.state === 'available' ? 0 : 11;
+    }
+    const probe = typeof rc.providerProbe === 'function' ? rc.providerProbe() : (await importTalosModule(ctx.repoRoot, 'provider-probe.mjs')).createProviderProbe({ leggiChiave: (p) => store.getKey(p), leggiRuntime: (p) => store.getRuntime(p) });
+    const result = await probe.prova(id);
+    writeValue(ctx, result);
+    return result?.esito === 'collegato' ? 0 : 11;
+} throw new Error(`Unsupported provider operation: ${op}`); }
+/*
+ * R2 (gate E14, E-03): `talos model list` for a person — one row per model under English columns, never the raw JSON array; the
+ * MODEL column is exactly what `talos model use` takes (OpenCode `opencode models` prints one id per line and JSON only with
+ * --verbose: `packages/opencode/src/cli/cmd/models.ts:36-46` at 1d6c3c0, 2026-09-24). `--json` keeps the rows unchanged.
+ */
+function contextText(value) {
+    if (!Number.isFinite(value) || Number(value) <= 0)
+        return t('key.models.unknown');
+    const n = Number(value);
+    return n >= 1_000_000 ? `${Number((n / 1_000_000).toFixed(1))}M` : n >= 1000 ? `${Math.round(n / 1000)}K` : String(n);
+}
+function flagText(value) { return value === true ? t('key.models.yes') : value === false ? t('key.models.no') : t('key.models.unknown'); }
+function sourceText(value) { return t(value === 'live' ? 'key.models.source.live' : value === 'configured' ? 'key.models.source.configured' : value === 'documented' ? 'key.models.source.documented' : 'key.models.source.unknown'); }
+export function modelListText(rows, notice) {
+    const head = notice ? `${notice}\n` : '';
+    if (!rows.length)
+        return `${head}${t('key.models.none')}\n`;
+    const table = [[t('key.models.column.model'), t('key.models.column.context'), t('key.models.column.tools'), t('key.models.column.reasoning'), t('key.models.column.availability')],
+        ...rows.map(row => [String(row?.id ?? ''), contextText(row?.contextWindow), flagText(row?.toolCalling), flagText(row?.reasoning), sourceText(row?.source ?? row?.available)])];
+    const widths = table[0].map((_, column) => Math.max(...table.map(line => line[column].length)));
+    const lines = table.map(line => line.map((cell, column) => column === line.length - 1 ? cell : cell.padEnd(widths[column])).join('  '));
+    return `${head}${lines.join('\n')}\n${t('key.models.use')}\n`;
+}
+export async function runModelCommand(ctx, args0) { const args = [...args0]; const op = args.shift() ?? 'list'; if (op === 'effort') {
+    const effort = args.shift();
+    if (!effort)
+        throw new Error('REASONING_EFFORT_REQUIRED');
+    const scope = (takeOption(args, '--scope') ?? 'user');
+    if (!['user', 'project-user'].includes(scope))
+        throw new Error('CONFIG_SCOPE_INVALID');
+    assertNoUnknownOptions(args);
+    const { configSet, configUnset } = await import("../config/commands.js");
+    if (effort === 'default') {
+        await configUnset({ paths: ctx.paths, projectRoot: ctx.projectRoot, scope, path: 'reasoningEffort' });
+        writeValue(ctx, { ok: true, reasoningEffort: null, scope }, `Cleared the ${scope} reasoning-effort override; a lower-precedence setting may still apply, otherwise the model default is used.\n`);
+        return 0;
+    }
+    if (!REASONING_EFFORTS.includes(effort))
+        throw new Error('CONFIG_INVALID_REASONING_EFFORT');
+    await configSet({ paths: ctx.paths, projectRoot: ctx.projectRoot, scope, path: 'reasoningEffort', value: effort });
+    writeValue(ctx, { ok: true, reasoningEffort: effort, scope }, `Using reasoning effort ${effort} (${scope})\n`);
+    return 0;
+} if (op === 'use') {
+    const id = args.shift();
+    if (!id)
+        throw new Error('MODEL_REQUIRED');
+    const scope = (takeOption(args, '--scope') ?? 'user');
+    if (!['user', 'project', 'project-user'].includes(scope))
+        throw new Error('CONFIG_SCOPE_INVALID');
+    assertNoUnknownOptions(args);
+    const provider = providerOfModel(id);
+    const registryModule = await importTalosModule(ctx.repoRoot, 'provider-registry.mjs');
+    if (!provider || !registryModule.REGISTRO_FORNITORI?.[provider])
+        throw Object.assign(new Error('MODEL_PROVIDER_INVALID'), { code: 'MODEL_PROVIDER_INVALID' });
+    const { configSet } = await import("../config/commands.js");
+    await configSet({ paths: ctx.paths, projectRoot: ctx.projectRoot, scope, path: 'model', value: id }); /* choosing a model chooses its provider: the interactive screen starts from the same choice */
+    createEnvironmentKeyConsent({ dataRoot: ctx.paths.dataRoot, registry: registryModule.REGISTRO_FORNITORI, env: {} }).chooseProvider(provider);
+    writeValue(ctx, { ok: true, model: id, scope }, `Using ${id} (${scope})\n`);
+    return 0;
+} if (op === 'list') {
+    const provider = takeOption(args, '--provider');
+    assertNoUnknownOptions(args);
+    const rc = await runtimeContext(ctx);
+    const catalog = rc.tuiCatalog;
+    if (provider) {
+        if (typeof catalog?.providerModels !== 'function')
+            throw Object.assign(new Error('PROVIDER_CATALOG_UNAVAILABLE'), { code: 'PROVIDER_CATALOG_UNAVAILABLE' });
+        const list = await catalog.providerModels(provider);
+        writeValue(ctx, list.rows, modelListText(list.rows, list.notice));
+        return 0;
+    }
+    if (typeof catalog?.listModels !== 'function')
+        throw Object.assign(new Error('PROVIDER_CATALOG_UNAVAILABLE'), { code: 'PROVIDER_CATALOG_UNAVAILABLE' });
+    const rows = await catalog.listModels();
+    writeValue(ctx, rows, modelListText(rows));
+    return 0;
+} throw new Error(`Unsupported model operation: ${op}`); }