firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/priority-requests.js

@@ -0,0 +1,70 @@
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { selectedWorld } from './world-access.js';
+import { recommendationReceiptMatches, recommendationRequestsMatch } from '../../contracts/recommendation-contracts.js';
+const keyPattern = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,127}$/;
+const invalid = () => new CliError('recommendation_request_invalid', 'The original priority request receipt could not be confirmed. No evaluation was repeated.');
+function checked(value, scope, turn, key) {
+    if (!recommendationReceiptMatches(value, { actor: scope.owner, workspace: scope.workspace, world: scope.world, turn }, key))
+        throw invalid();
+    return value;
+}
+export function priorityRequestText(value) {
+    return `Request: ${value.request_key}\n${value.state === 'accepted'
+        ? value.resource_available ? `Priority assessment accepted\n${value.batch_id}\nAcceptance is not a completed score. No evaluation or agent execution was repeated.`
+            : 'The request was accepted, but its priority assessment is no longer available.'
+        : value.state === 'withdrawn' ? 'Canceled before acceptance. This request cannot start a priority assessment.'
+            : 'No acceptance is recorded yet. The original request may still arrive. Check it again or cancel only this unaccepted request.'}`;
+}
+export async function inspectPriorityRequest(scope, turn, key, signal) {
+    const params = new URLSearchParams({ turn_id: identifier(turn), request_key: key });
+    if (!keyPattern.test(key))
+        throw invalid();
+    return checked(await api(`${scope.prefix}/recommendation-request?${params}`, {
+        actor: scope.owner, workspace: scope.workspace, signal
+    }), scope, turn, key);
+}
+export async function priorityRequests(args, options, output) {
+    const action = args[0], history = action === 'requests';
+    if (!['requests', 'request', 'withdraw-request'].includes(action) || args.length !== (history ? 2 : 3)
+        || !history && (options.page !== undefined || options.search !== undefined || options.status !== undefined)
+        || action !== 'withdraw-request' && options.approve)
+        throw new CliError('arguments_invalid', 'Use priority requests <turn>, request <turn> <key>, or withdraw-request <turn> <key>. Choose the saved world with --world.', 2);
+    const turn = identifier(args[1]), key = args[2];
+    if (!history && !keyPattern.test(key))
+        throw invalid();
+    const page = options.page ?? '1', query = options.search ?? '', status = options.status ?? '';
+    if (!/^[1-9][0-9]{0,8}$/.test(page) || query.length > 200 || /[\u0000-\u001f\u007f]/u.test(query) || !['', 'accepted', 'withdrawn'].includes(status))
+        throw new CliError('arguments_invalid', 'Use a positive page, request-key search of up to 200 characters and accepted or withdrawn status.', 2);
+    const interactive = !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+    const scope = await selectedWorld({ ...options, interactive });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    if (history) {
+        const params = new URLSearchParams({ turn_id: turn, page, q: query, status });
+        const result = await api(`${scope.prefix}/recommendation-requests?${params}`, auth);
+        if (!recommendationRequestsMatch(result, { actor: scope.owner, workspace: scope.workspace, world: scope.world, turn, query, status }))
+            throw invalid();
+        const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+        output(result, (result.results.map(value => priorityRequestText(checked(value, scope, turn))).join('\n\n') || 'No matching priority requests from your account.')
+            + `\nPage ${result.page}, ${result.count} requests.${result.next ? `\nContinue: firedrill priority requests ${turn} --world ${scope.world} --workspace ${scope.workspace} --page ${result.page + 1}${query ? ' --search ' + quote(query) : ''}${status ? ' --status ' + status : ''}${options.json ? ' --json' : ''}` : ''}`);
+        return;
+    }
+    if (action === 'request') {
+        const value = await inspectPriorityRequest(scope, turn, key, options.signal);
+        output(value, priorityRequestText(value));
+        return;
+    }
+    if (!options.approve) {
+        if (!interactive)
+            throw new CliError('approval_required', 'Use --approve-assessment to cancel this exact unaccepted request. Accepted assessments are only inspected.', 2);
+        if (!await selectOne('Cancel this unaccepted priority request? An accepted assessment will only be inspected.', [
+            { value: false, label: 'Keep request' }, { value: true, label: 'Cancel unaccepted request' }
+        ], options.signal))
+            return;
+    }
+    const value = checked(await api(`${scope.prefix}/recommendation-request`, { ...auth, method: 'POST',
+        body: { turn_id: turn, request_key: key } }), scope, turn, key);
+    output(value, priorityRequestText(value));
+}

package/dist/cli/src/priority.js

@@ -0,0 +1,223 @@
+import { workspaceLink } from './browser-links.js';
+import { randomUUID } from 'node:crypto';
+import { api } from './auth.js';
+import { remember, recovery } from './evaluation-authoring.js';
+import { CliError } from './http.js';
+import { priorityRequests } from './priority-requests.js';
+import { selectMany, selectOne } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { selectedWorkspace, selectedWorld } from './world-access.js';
+import { recommendationBatchMatches, recommendationBatchesMatch, recommendationTurnsMatch, recommendationDetailMatches, recommendationRecoveryMatches } from '../../contracts/recommendation-contracts.js';
+const names = { queued: 'Queued', preparing: 'Preparing context', submitted: 'Assessing priority',
+    succeeded: 'Assessed', not_assessable: 'Not assessable', failed: 'Evaluation error', unknown: 'Reply unconfirmed', unavailable: 'Context unavailable' };
+const invalid = () => new CliError('recommendation_response_invalid', 'The saved proposal priority response could not be confirmed. No evaluation or agent execution was repeated.');
+const interactive = (options) => !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+const auth = (scope, options) => ({ actor: scope.owner, workspace: scope.workspace, signal: options.signal });
+function pageOf(value, page, maximum = 100) {
+    if (!value || !Array.isArray(value.results) || value.results.length > maximum || value.page !== page
+        || !Number.isSafeInteger(value.count) || value.count < 0 || !Number.isSafeInteger(value.page_size)
+        || value.page_size < 1 || value.page_size > maximum || value.results.length > value.page_size
+        || value.next !== null && typeof value.next !== 'string')
+        throw invalid();
+    return value;
+}
+function checkedBatch(value, scope, id, turn) {
+    if (!recommendationBatchMatches(value, { workspace: scope.workspace, world: scope.world, turn }, id)
+        || typeof value.created_at !== 'string' || typeof value.model !== 'string')
+        throw invalid();
+    return value;
+}
+async function chooseTurn(scope, options, requested) {
+    let number = 1;
+    while (true) {
+        const data = pageOf(await api(`${scope.prefix}/recommendation-turns?page=${number}${requested ? '&turn_id=' + identifier(requested) : ''}`, auth(scope, options)), number);
+        if (!recommendationTurnsMatch(data, { workspace: scope.workspace, world: scope.world }, requested))
+            throw invalid();
+        if (!data.can_assess)
+            throw new CliError('recommendation_unavailable', 'Priority assessment needs write access and a configured evaluator. Saved reports remain readable.');
+        for (const one of data.results) {
+            identifier(one.id);
+            identifier(one.response_id);
+            if (!Number.isSafeInteger(one.proposal_count) || one.proposal_count < 1 || typeof one.created_at !== 'string')
+                throw invalid();
+        }
+        if (requested) {
+            if (data.results.length !== 1 || data.results[0].id !== requested)
+                throw new CliError('recommendation_selection_changed', 'This response has no current pending proposals. Inspect the world before another request.');
+            return data.results[0];
+        }
+        const choices = data.results.map(one => ({ value: one.id, label: `${one.proposal_count} pending proposals · ${one.created_at}` }));
+        if (number > 1)
+            choices.unshift({ value: 'previous', label: 'Previous page' });
+        if (data.next)
+            choices.push({ value: 'next', label: 'Next page' });
+        choices.push({ value: 'cancel', label: 'Cancel' });
+        if (!data.results.length && number === 1)
+            throw new CliError('recommendation_selection_empty', 'No current proposals are ready. No priority assessment was requested.');
+        const selected = await selectOne('Proposal response', choices, options.signal);
+        if (selected === 'cancel')
+            throw new CliError('canceled', 'No priority assessment was requested.', 130);
+        if (selected === 'previous') {
+            number -= 1;
+            continue;
+        }
+        if (selected === 'next') {
+            number += 1;
+            continue;
+        }
+        const turn = data.results.find(one => one.id === selected);
+        if (!turn)
+            throw invalid();
+        return turn;
+    }
+}
+async function chooseProposals(scope, options, requestedTurn) {
+    const turn = await chooseTurn(scope, options, requestedTurn), selected = new Set();
+    let number = 1;
+    while (true) {
+        const data = pageOf(await api(`${scope.prefix}/messages/${turn.response_id}/proposals?page=${number}&page_size=25`, auth(scope, options)), number, 25);
+        if (data.message_id !== turn.response_id)
+            throw invalid();
+        const eligible = data.results.filter(one => one.state === 'pending' && !one.stale && one.evidence_available);
+        for (const one of data.results)
+            if (one.turn_id !== turn.id)
+                throw invalid();
+        for (const one of data.results)
+            if (!eligible.some(item => item.id === one.id))
+                selected.delete(one.id);
+        if (eligible.length) {
+            const chosen = await selectMany(`Proposals · ${selected.size} selected`, eligible.map(one => ({ value: identifier(one.id),
+                label: one.title, detail: `${one.scenario_count} scenarios · ${one.purpose}` })), options.signal, [...selected]);
+            for (const one of eligible)
+                selected.delete(one.id);
+            for (const one of chosen)
+                selected.add(one);
+            if (selected.size > 64)
+                throw new CliError('recommendation_selection_capacity', 'Choose up to 64 proposals in one priority request. No request was submitted.', 2);
+        }
+        const choices = [];
+        if (selected.size)
+            choices.push({ value: 'create', label: `Review ${selected.size} selected proposals` });
+        if (data.next)
+            choices.push({ value: 'next', label: 'Next proposal page' });
+        if (number > 1)
+            choices.push({ value: 'previous', label: 'Previous proposal page' });
+        choices.push({ value: 'cancel', label: 'Cancel' });
+        const action = await selectOne(eligible.length ? 'Continue' : 'No eligible proposals on this page', choices, options.signal);
+        if (action === 'cancel')
+            throw new CliError('canceled', 'No priority assessment was requested.', 130);
+        if (action === 'next') {
+            number += 1;
+            continue;
+        }
+        if (action === 'previous') {
+            number -= 1;
+            continue;
+        }
+        return { turn_id: turn.id, proposal_ids: [...selected].sort(), share_context: true };
+    }
+}
+function detailText(value, workspace) {
+    if (!Array.isArray(value.results) || value.results.length > 64 || !value.rubric || !Array.isArray(value.rubric.levels)
+        || value.rubric.levels.length < 2 || value.rubric.levels.length > 10 || typeof value.rubric.instructions !== 'string'
+        || value.rubric.levels.some(one => typeof one !== 'string') || !value.context)
+        throw invalid();
+    const rows = value.results.map(one => {
+        if (!one || !Object.hasOwn(names, one.state) || typeof one.title !== 'string' || typeof one.requested_model !== 'string'
+            || one.model !== null && typeof one.model !== 'string')
+            throw invalid();
+        let score = names[one.state];
+        if (one.result?.score != null) {
+            if (one.state !== 'succeeded' || !one.model || !Number.isFinite(one.result.score) || !Array.isArray(one.result.levels)
+                || one.result.levels.length !== value.rubric.levels.length || one.result.score < 0 || one.result.score > value.rubric.levels.length - 1)
+                throw invalid();
+            score = `Priority ${one.result.score.toLocaleString(undefined, { maximumFractionDigits: 2 })} / ${value.rubric.levels.length - 1}`;
+        }
+        if (!Array.isArray(one.evidence_refs) || one.evidence_refs.length > 20)
+            throw invalid();
+        const citations = one.evidence_refs.map((ref, index) => {
+            if (!ref || typeof ref.record_id !== 'string' || typeof ref.kind !== 'string')
+                throw invalid();
+            const id = identifier(ref.record_id), pattern = /^\/campaigns\/([a-f0-9-]{36})\/trials\/([a-f0-9-]{36})\?view=(conversation|actions)&record=([a-f0-9-]{36})$/;
+            const match = typeof ref.path === 'string' ? ref.path.match(pattern) : null;
+            if (!match || !['message', 'action'].includes(ref.kind) || match[4] !== id
+                || match[3] !== (ref.kind === 'message' ? 'conversation' : 'actions'))
+                throw invalid();
+            identifier(match[1]);
+            identifier(match[2]);
+            return `${ref.kind === 'message' ? 'Conversation evidence' : 'Tool action evidence'} ${index + 1}: ${workspaceLink(workspace, ref.path)}`;
+        });
+        return `${one.title}\n${score} · ${one.model ?? `Requested ${one.requested_model}`}${one.problem ? '\n' + one.problem : ''}${citations.length ? '\n' + citations.join('\n') : ''}`;
+    });
+    return [value.id, ...rows, 'Priority scale', ...value.rubric.levels.map((one, index) => `${index}: ${one}`),
+        value.rubric.instructions, `World revision ${value.context.world_revision}. Up to ${value.context.sample_per_kind} declarations of each kind and the proposal's cited observations were supplied.`,
+        'This is proposal priority, not an agent quality score, confirmed defect or probability of failure. No proposal was applied.'].join('\n\n');
+}
+export async function priorityCommand(args, options, output) {
+    const action = args[0] ?? 'create';
+    if (['requests', 'request', 'withdraw-request'].includes(action)) {
+        if (options.request)
+            throw new CliError('arguments_invalid', 'Use the original request key as an argument for priority request inspection.', 2);
+        return priorityRequests(args, options, (data, readable) => output('result', data, readable));
+    }
+    if (!['create', 'list', 'show', 'recover-replies', 'resume', 'forget'].includes(action) || options.search !== undefined || options.status !== undefined)
+        throw new CliError('arguments_invalid', 'Use priority, create <turn> <proposal...>, list <turn>, show <batch>, recover-replies <batch>, resume or forget.', 2);
+    if (['resume', 'forget'].includes(action))
+        return recovery('priority', args, await selectedWorkspace({ ...options, interactive: interactive(options) }), options, output);
+    if (action !== 'list' && options.page !== undefined || action !== 'create' && action !== 'recover-replies' && (options.request || options.approve))
+        throw new CliError('arguments_invalid', 'Use paging only with priority list, and request/consent options only with the intended change.', 2);
+    if (action === 'create' ? args.length > 66 : args.length !== 2)
+        throw new CliError('arguments_invalid', 'Use priority for guided selection, or create <turn> <proposal...>. List/show/recover-replies take one saved ID.', 2);
+    const scope = await selectedWorld({ ...options, interactive: interactive(options) });
+    if (action === 'create') {
+        let body;
+        if (args.length > 2) {
+            const proposals = args.slice(2).map(identifier);
+            if (new Set(proposals).size !== proposals.length)
+                throw new CliError('arguments_invalid', 'Choose distinct proposal IDs.', 2);
+            body = { turn_id: identifier(args[1]), proposal_ids: proposals.sort(), share_context: true };
+        }
+        else {
+            if (!interactive(options))
+                throw new CliError('recommendation_selection_required', 'Use priority create <turn-id> <proposal-id...> --approve-assessment in automation, or run priority in a terminal for guided selection.', 2);
+            body = await chooseProposals(scope, options, args[1] ? identifier(args[1]) : undefined);
+        }
+        if (!options.approve && !(interactive(options) && await selectOne('Assess priority using the selected proposals and cited observations? Keep a private recovery record. This does not run the agent or apply a proposal.', [{ value: false, label: 'Cancel' }, { value: true, label: 'Assess proposal priority' }], options.signal)))
+            throw new CliError('recommendation_consent_required', 'No priority assessment was submitted. Automation requires --approve-assessment after reviewing the selected context.', 2);
+        await remember('priority', `${scope.prefix}/recommendation-batches`, body, scope, options, output);
+        return;
+    }
+    const id = identifier(args[1]);
+    if (action === 'list') {
+        const number = options.page ?? '1';
+        if (!/^[1-9][0-9]{0,8}$/.test(number))
+            throw new CliError('arguments_invalid', 'Choose a positive priority history page.', 2);
+        const data = pageOf(await api(`${scope.prefix}/recommendation-batches?turn_id=${id}&page=${number}`, auth(scope, options)), Number(number));
+        if (!recommendationBatchesMatch(data, { workspace: scope.workspace, world: scope.world, turn: id }))
+            throw invalid();
+        output('result', data, (data.results.map(one => {
+            checkedBatch(one, scope, undefined, id);
+            return `${one.id}\n${one.created_at} · ${one.proposal_count} proposals\n${Object.entries(one.states).map(([state, count]) => `${names[state]}: ${count}`).join(', ')}`;
+        }).join('\n\n') || 'No priority assessments for this response.') + `\nPage ${data.page}, ${data.count} assessments.${data.next
+            ? `\nContinue: firedrill priority list ${id} --workspace ${scope.workspace} --world ${scope.world} --page ${data.page + 1}${options.json ? ' --json' : ''}` : ''}`);
+        return;
+    }
+    if (action === 'show') {
+        const result = await api(`${scope.prefix}/recommendation-batches/${id}`, auth(scope, options));
+        checkedBatch(result, scope, id);
+        if (!recommendationDetailMatches(result, { workspace: scope.workspace, world: scope.world }, id))
+            throw invalid();
+        output('result', result, detailText(result, scope.workspace));
+        return;
+    }
+    if (!options.approve && !(interactive(options) && await selectOne('Read only saved assessments? This will not request another assessment or run the agent again.', [{ value: false, label: 'Cancel' }, { value: true, label: 'Check saved replies' }], options.signal)))
+        throw new CliError('recommendation_consent_required', 'Use --approve-assessment to request an original saved-reply check.', 2);
+    const key = options.request ? identifier(options.request) : randomUUID();
+    output('recovery_request', { batch_id: id, request_key: key }, `Request: ${key}\nIf interrupted: firedrill priority recover-replies ${id} --world ${scope.world} --workspace ${scope.workspace} --request-key ${key} --approve-assessment`);
+    const result = await api(`${scope.prefix}/recommendation-batches/${id}/recover-replies`, {
+        ...auth(scope, options), method: 'POST', body: {}, idempotencyKey: key
+    });
+    if (!recommendationRecoveryMatches(result, { workspace: scope.workspace, world: scope.world, actor: scope.owner }, id, key))
+        throw invalid();
+    output('result', result, result.requested ? 'Original saved-reply check requested. No new evaluation was submitted.' : 'No unconfirmed original replies to check.');
+}

package/dist/cli/src/prompts.js

@@ -0,0 +1,184 @@
+import { emitKeypressEvents } from 'node:readline';
+import { createInterface } from 'node:readline/promises';
+import { CliError } from './http.js';
+let accessible = false, interactive = true;
+export function configurePrompts(options) {
+    accessible = options.accessible === true;
+    interactive = options.interactive !== false;
+}
+export const plainPromptMode = () => accessible || process.env.FIREDRILL_ACCESSIBLE === '1' || process.env.TERM === 'dumb' || process.env.NO_COLOR !== undefined;
+async function lineChoices(title, choices, multiple, signal, initial = []) {
+    // Same current server page as the interactive widget, never tenant-wide data.
+    process.stderr.write(terminalText(title) + '\n');
+    choices.forEach((choice, index) => process.stderr.write(`${index + 1}. ${terminalText(choice.label)}${choice.detail ? ': ' + terminalText(choice.detail) : ''}${initial.includes(choice.value) ? ' (selected)' : ''}\n`));
+    const prompt = createInterface({ input: process.stdin, output: process.stderr, terminal: false });
+    const closed = new AbortController();
+    prompt.once('close', () => closed.abort());
+    const active = signal ? AbortSignal.any([signal, closed.signal]) : closed.signal;
+    try {
+        while (true) {
+            active.throwIfAborted();
+            const answer = (await prompt.question(multiple ? 'Numbers separated by commas; Enter keeps selection; none clears; q cancels: '
+                : 'Choose a number, or q to cancel: ', { signal: active })).trim();
+            if (answer.toLowerCase() === 'q')
+                throw new CliError('canceled', 'Selection canceled.', 130);
+            if (multiple && !answer)
+                return choices.filter(choice => initial.includes(choice.value)).map(choice => choice.value);
+            if (multiple && answer.toLowerCase() === 'none')
+                return [];
+            const parts = answer.split(',').map(value => value.trim());
+            if ((!multiple && parts.length !== 1) || parts.some(value => !/^[1-9][0-9]*$/.test(value)
+                || !Number.isSafeInteger(Number(value)) || Number(value) > choices.length)
+                || new Set(parts.map(Number)).size !== parts.length) {
+                process.stderr.write('Choose only the listed numbers.\n');
+                continue;
+            }
+            return parts.map(Number).sort((a, b) => a - b).map(number => choices[number - 1].value);
+        }
+    }
+    catch (error) {
+        if (active.aborted)
+            throw new CliError('canceled', 'Selection canceled.', 130);
+        throw error;
+    }
+    finally {
+        prompt.close();
+    }
+}
+export function terminalText(value) {
+    // Strip terminal control sequences, including OSC hyperlinks and bidi marks.
+    // Preserve the underlying string in --json output instead of rewriting data.
+    return String(value).replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, ' ');
+}
+async function choose(title, choices, multiple, signal, initial = []) {
+    if (!interactive || !process.stdin.isTTY || !process.stderr.isTTY) {
+        throw new CliError('selection_required', 'Choose an item using its command option. Interactive selection requires a terminal.', 2);
+    }
+    if (!choices.length)
+        throw new CliError('selection_empty', 'No available items match this selection.');
+    if (plainPromptMode())
+        return lineChoices(title, choices, multiple, signal, initial);
+    emitKeypressEvents(process.stdin);
+    let index = 0, rendered = 0;
+    const selected = new Set(choices.flatMap((choice, index) => initial.includes(choice.value) ? [index] : []));
+    function draw() {
+        if (rendered)
+            process.stderr.write(`\x1b[${rendered}A\x1b[J`);
+        const limit = Math.max(2, Math.min(8, (process.stderr.rows ?? 24) - 6));
+        const first = Math.max(0, Math.min(index - Math.floor(limit / 2), choices.length - limit));
+        const lines = [terminalText(title)];
+        choices.slice(first, first + limit).forEach((choice, offset) => {
+            const position = offset + first;
+            const marker = multiple ? selected.has(position) ? '[x]' : '[ ]' : index === position ? '(●)' : '( )';
+            lines.push(`${index === position ? '›' : ' '} ${marker} ${terminalText(choice.label).slice(0, Math.max(10, (process.stderr.columns ?? 80) - 12))}`);
+            if (index === position && choice.detail)
+                lines.push(`      ${terminalText(choice.detail).slice(0, Math.max(10, (process.stderr.columns ?? 80) - 12))}`);
+        });
+        lines.push(multiple ? '↑↓ move · Space select · Enter continue · Esc cancel' : '↑↓ move · Enter select · Esc cancel');
+        process.stderr.write(lines.join('\n') + '\n');
+        rendered = lines.length;
+    }
+    const wasRaw = process.stdin.isRaw;
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stderr.write('\x1b[?25l');
+    try {
+        return await new Promise((resolve, reject) => {
+            const finish = (error) => {
+                process.stdin.off('keypress', onKey);
+                signal?.removeEventListener('abort', onAbort);
+                if (error)
+                    reject(error);
+                else
+                    resolve(multiple ? [...selected].sort((a, b) => a - b).map(position => choices[position].value) : [choices[index].value]);
+            };
+            const onAbort = () => finish(new CliError('canceled', 'Selection canceled.', 130));
+            const onKey = (_character, key) => {
+                if (key.name === 'escape' || key.ctrl && key.name === 'c') {
+                    finish(new CliError('canceled', 'Selection canceled.', 130));
+                    return;
+                }
+                if (key.name === 'return') {
+                    finish();
+                    return;
+                }
+                if (key.name === 'up')
+                    index = (index - 1 + choices.length) % choices.length;
+                else if (key.name === 'down')
+                    index = (index + 1) % choices.length;
+                else if (multiple && key.name === 'space') {
+                    if (selected.has(index))
+                        selected.delete(index);
+                    else
+                        selected.add(index);
+                }
+                else
+                    return;
+                draw();
+            };
+            process.stdin.on('keypress', onKey);
+            signal?.addEventListener('abort', onAbort, { once: true });
+            if (signal?.aborted)
+                onAbort();
+            else
+                draw();
+        });
+    }
+    finally {
+        process.stdin.setRawMode(wasRaw);
+        process.stdin.pause();
+        process.stderr.write('\x1b[?25h');
+    }
+}
+export async function selectOne(title, choices, signal) { return (await choose(title, choices, false, signal))[0]; }
+export async function selectMany(title, choices, signal, initial = []) { return choose(title, choices, true, signal, initial); }
+/** A value is never echoed, retained on disk or placed in command arguments. */
+export async function secretLine(title, signal) {
+    if (!interactive || !process.stdin.isTTY || !process.stderr.isTTY)
+        throw new CliError('value_input_required', 'Use an interactive terminal or pipe the exact value with --value-stdin. Do not pass secrets in command arguments.', 2);
+    emitKeypressEvents(process.stdin);
+    const wasRaw = process.stdin.isRaw;
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stderr.write(`${terminalText(title)} (hidden): `);
+    let value = '';
+    try {
+        return await new Promise((resolve, reject) => {
+            const finish = (error) => {
+                process.stdin.off('keypress', onKey);
+                signal.removeEventListener('abort', onAbort);
+                process.stderr.write('\n');
+                if (error)
+                    reject(error);
+                else
+                    resolve(value);
+                value = '';
+            };
+            const onAbort = () => finish(new CliError('canceled', 'Value entry canceled. No save was submitted.', 130));
+            const onKey = (character, key) => {
+                if (key.name === 'escape' || key.ctrl && key.name === 'c')
+                    return onAbort();
+                if (key.name === 'return')
+                    return finish();
+                if (key.name === 'backspace') {
+                    value = Array.from(value).slice(0, -1).join('');
+                    return;
+                }
+                if (key.ctrl || key.meta || !character || /[\u0000-\u001f\u007f-\u009f]/.test(character))
+                    return;
+                if (Buffer.byteLength(value + character) > 65536)
+                    return finish(new CliError('value_capacity', 'This value exceeds secure-entry capacity. No save was submitted.', 2));
+                value += character;
+            };
+            process.stdin.on('keypress', onKey);
+            signal.addEventListener('abort', onAbort, { once: true });
+            if (signal.aborted)
+                onAbort();
+        });
+    }
+    finally {
+        value = '';
+        process.stdin.setRawMode(wasRaw);
+        process.stdin.pause();
+    }
+}