firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/simple/tool-renewal.js

@@ -0,0 +1,308 @@
+// `firedrill tools session <session-id> renew ...`: extend a running tool
+// session's shared-pool tools on the same live batch, with the same tools and
+// data and nothing restarted. Root reviews the extension under a request key
+// printed before anything is sent and quotes it at once; nothing is reserved or
+// extended until the human approves that exact estimate. A rerun with the
+// printed key continues the original review, never a second one, and a lost
+// approval is read back, never charged twice. An unused review is closed
+// explicitly, and a review request whose answer was lost is read back by its
+// key or withdrawn. Nothing here renews automatically: it is never a heartbeat.
+// Isolated tools keep their own lifetime, and drill-owned tools never extend a
+// campaign's deadline.
+import { randomUUID } from 'node:crypto';
+import { approveCredits } from './credit-approval.js';
+import { CliError } from '../http.js';
+import { selectOne, terminalText } from '../prompts.js';
+import { errorCode, isTransient, retryTransient } from '../native/control-plane.js';
+import { applyRenewal, cancelRenewal, getRenewal, listRenewals, recoverRenewal, renewalId, reviewRenewal, withdrawRenewal, RENEWAL_MAX_SECONDS, RENEWAL_MIN_SECONDS, } from '../native/standalone-renewals.js';
+import { STANDALONE_ACTIVE } from '../native/standalone-tools.js';
+import { amount } from './plan-apply.js';
+/** The verbs this module owns under `tools session <session-id>`. */
+export const RENEWAL_VERBS = new Set(['renew', 'renewals', 'renewal', 'cancel-renewal', 'renewal-request', 'withdraw-renewal']);
+/** An estimate this close to expiry is not approved: approval would race it. */
+const QUOTE_MARGIN_MS = 60_000;
+const RECOVER_MS = 15_000;
+// Closed public transport/authority/billing categories only. Never copy an
+// arbitrary server/provider code, message, response body or exception cause.
+const RENEWAL_DIAGNOSTIC_CODES = new Set([
+    'request_failed', 'connection_uncertain', 'response_unavailable', 'native_disconnected', 'native_response_unconfirmed',
+    'native_authorization_refresh_pending', 'agent_authorization_refresh_pending',
+    'identity_service_unavailable', 'identity_refresh_capacity', 'identity_refresh_configuration_required',
+    'billing_credit_policy_unavailable', 'billing_credit_unit_definition_required', 'billing_seat_policy_unavailable',
+]);
+function renewalDiagnostic(emit, phase, error, recovery) {
+    const original = error instanceof CliError ? error : null;
+    const code = original && RENEWAL_DIAGNOSTIC_CODES.has(original.code) ? original.code : 'unknown';
+    const httpStatus = original?.httpStatus;
+    const http_status = typeof httpStatus === 'number' && Number.isInteger(httpStatus)
+        && httpStatus >= 100 && httpStatus <= 599 ? httpStatus : null;
+    const candidate = original?.requestId;
+    const request_id = typeof candidate === 'string' && (/^[a-f0-9]{32}$/.test(candidate)
+        || /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(candidate)) ? candidate : null;
+    const description = recovery === 'not_found' ? 'The recovery read did not find the original request.'
+        : recovery === 'still_reviewed' ? 'The original renewal is still reviewed, not confirmed as applied.'
+            : 'The recovery read could not be completed.';
+    emit('tool_renewal_diagnostic', { phase, original_error: { code, http_status, request_id }, recovery }, 'Renewal ' + phase + ' was not confirmed. Original error ' + code
+        + (http_status === null ? '' : ' (HTTP ' + http_status + ')') + '. '
+        + (request_id === null ? '' : 'Support reference ' + request_id + '. ') + description);
+}
+const STATE_TEXT = {
+    reviewed: 'reviewed, not approved (nothing reserved or extended)',
+    applied: 'applied',
+    cancelled: 'closed without extending anything',
+};
+const tty = (options) => !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+const tools = (n) => `${n} shared-pool tool${n === 1 ? '' : 's'}`;
+const seconds = (value) => value % 86_400 === 0 ? `${value / 86_400} day${value === 86_400 ? '' : 's'}`
+    : value % 3_600 === 0 ? `${value / 3_600} hour${value === 3_600 ? '' : 's'}` : value % 60 === 0 ? `${value / 60} minutes` : `${value} seconds`;
+function renewSeconds(value) {
+    if (value === undefined)
+        return null;
+    if (!/^[1-9][0-9]{0,8}$/.test(value) || Number(value) < RENEWAL_MIN_SECONDS || Number(value) > RENEWAL_MAX_SECONDS) {
+        throw new CliError('tool_duration_invalid', `Use --seconds with a whole number from ${RENEWAL_MIN_SECONDS} to ${RENEWAL_MAX_SECONDS} (one year). Nothing was sent.`, 2);
+    }
+    return Number(value);
+}
+function pageNumber(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^[1-9][0-9]{0,6}$/.test(value))
+        throw new CliError('arguments_invalid', 'Use --page with a positive page number.', 2);
+    return Number(value);
+}
+/** Root changes a session's renewals only for the person who started it; anyone else gets a 404. */
+const ownerOnly = (error) => {
+    if (error instanceof CliError && error.httpStatus === 404) {
+        throw new CliError('tool_renewal_not_owner', 'Only the person who started this tool session can extend it or change its renewals. Nothing was reserved or extended.', 2);
+    }
+    throw error;
+};
+const withdrawnError = (requestKey) => new CliError('native_tool_request_withdrawn', `Renewal request ${requestKey} was withdrawn and can never be reviewed. Start a new renewal without --request-key.`, 2);
+const mapWithdrawn = (requestKey) => (error) => {
+    if (errorCode(error) === 'native_tool_request_withdrawn')
+        throw withdrawnError(requestKey);
+    throw error;
+};
+function renewalText(target, row) {
+    return [
+        `Renewal ${row.id} of tool session ${target.sessionId}: ${STATE_TEXT[row.state]}`,
+        `  ${tools(row.instance_count)}: +${seconds(row.additional_seconds)}, end ${terminalText(row.previous_expires_at)} -> ${terminalText(row.new_expires_at)}`,
+        `  Request ${row.request_key}, reviewed ${terminalText(row.created_at)}${row.applied_at ? `, applied ${terminalText(row.applied_at)}` : ''}`,
+    ].join('\n');
+}
+function quoteText(target, row) {
+    return [
+        `Extend ${tools(row.instance_count)} of tool session ${target.sessionId} by ${seconds(row.additional_seconds)}: `
+            + `they would run until ${terminalText(row.new_expires_at)} instead of ${terminalText(row.previous_expires_at)}. Same tools and data; nothing restarts.`,
+        target.isolatedTools ? `${target.isolatedTools} isolated tool${target.isolatedTools === 1 ? '' : 's'} in this session keep their current end time.` : null,
+        `Cloud-work estimate (maximum, reserved only once approved): ${amount(row.quote.maximum_units, row.quote.credit_scale, row.quote.denomination)}`,
+        `Estimate expires: ${terminalText(row.quote.expires_at)}`,
+    ].filter((line) => line !== null).join('\n');
+}
+async function consent(question, detail, retry, options) {
+    let approved = options.approve === true;
+    if (!approved && tty(options)) {
+        approved = await selectOne(question, [
+            { value: false, label: 'Not now', detail: 'Nothing is sent.' },
+            { value: true, label: 'Yes', detail },
+        ], options.signal);
+    }
+    if (!approved)
+        throw new CliError('tool_change_consent_required', `Nothing was sent. After the human approves: ${retry} --approve-tool-change`, 2);
+}
+/**
+ * `renew --seconds <n> [--request-key <key>] [--usage-quote <quote-id>] [--approve-tool-change]`.
+ * The review is continued by its key; approval names the exact quote the human saw.
+ */
+async function renew(scope, target, options, emit) {
+    const signal = options.signal;
+    const batchId = target.batch.id;
+    const wanted = renewSeconds(options.seconds);
+    if (options.quote !== undefined && options.request === undefined) {
+        throw new CliError('arguments_invalid', 'Use --usage-quote with the --request-key that was printed with it. Nothing was sent.', 2);
+    }
+    const quoteGiven = options.quote === undefined ? undefined : renewalId(options.quote, 'quote id');
+    const requestKey = options.request === undefined ? randomUUID() : renewalId(options.request, 'request key');
+    const recovery = `firedrill tools session ${target.sessionId} renew${wanted ? ` --seconds ${wanted}` : ''} --request-key ${requestKey}`;
+    const read = `firedrill tools session ${target.sessionId} renewal-request ${requestKey}`;
+    const withdraw = `firedrill tools session ${target.sessionId} withdraw-renewal ${requestKey}`;
+    // A renewal already reviewed under this key is continued, never reviewed again.
+    let renewal = options.request === undefined ? null : await recoverRenewal(scope, { batchId, requestKey, signal }).catch(mapWithdrawn(requestKey));
+    if (renewal && wanted !== null && renewal.additional_seconds !== wanted) {
+        throw new CliError('idempotency_conflict', `That renewal was reviewed for ${seconds(renewal.additional_seconds)}. Continue it without --seconds, `
+            + 'or start a new one without --request-key.', 2);
+    }
+    if (!renewal) {
+        if (wanted === null)
+            throw new CliError('tool_duration_required', 'Use --seconds <n> to say how much longer the tools run. Nothing was sent.', 2);
+        const batch = target.batch;
+        if (batch.state !== STANDALONE_ACTIVE || batch.stop_requested_at || !batch.expires_at || Date.parse(batch.expires_at) <= Date.now()) {
+            throw new CliError('tool_renewal_not_live', `Only a running tool session can be extended; this one is ${terminalText(batch.state)}`
+                + `${batch.stop_requested_at ? ' and stopping' : ''}. Start a new session instead. Nothing was sent.`, 2);
+        }
+        emit('tool_renewal_request', { session_id: target.sessionId, batch_id: batchId, additional_seconds: wanted, request_key: requestKey }, `Renewal request: ${requestKey}\nIf interrupted, continue with ${recovery}. Do not start again under a new key.`);
+        try {
+            renewal = await reviewRenewal(scope, { batchId, requestKey, seconds: wanted, signal });
+        }
+        catch (error) {
+            if (errorCode(error) === 'native_tool_request_withdrawn')
+                throw withdrawnError(requestKey);
+            if (error instanceof CliError && error.httpStatus === 404)
+                ownerOnly(error);
+            // Only an unanswered (or cancelled) review may have landed; a refusal or a bad local input is reported as it is.
+            if (!signal.aborted && !isTransient(error) && errorCode(error) !== 'native_response_unconfirmed')
+                throw error;
+            let recoveryState = 'not_found';
+            renewal = await recoverRenewal(scope, { batchId, requestKey, signal: AbortSignal.timeout(RECOVER_MS) })
+                .catch(() => { recoveryState = 'read_failed'; return null; });
+            if (!renewal) {
+                renewalDiagnostic(emit, 'review', error, recoveryState);
+                throw new CliError('tool_renewal_unconfirmed', `The renewal request was not confirmed. Read it with ${read}; continue it with ${recovery}; `
+                    + `or, if the human decides it must never be reviewed, withdraw it with ${withdraw} (which undoes nothing).`);
+            }
+        }
+    }
+    const reviewed = renewal;
+    if (wanted !== null && reviewed.additional_seconds !== wanted) {
+        throw new CliError('idempotency_conflict', 'The recovered original renewal has a different duration. Read it by its request key before continuing. Nothing was approved.', 2);
+    }
+    if (reviewed.state !== 'reviewed') {
+        // Already applied or closed: shown as it is, never approved again.
+        emit('tool_renewal', reviewed, renewalText(target, reviewed)
+            + (reviewed.state === 'cancelled' ? '\nThis review was closed. To extend the tools, start a new renewal without --request-key.' : ''));
+        return;
+    }
+    const cancel = `firedrill tools session ${target.sessionId} cancel-renewal ${reviewed.id}`;
+    if (Date.parse(reviewed.quote.expires_at) - Date.now() <= QUOTE_MARGIN_MS) {
+        throw new CliError('tool_quote_expired', 'This estimate has expired or expires within a minute. Nothing was reserved or extended. '
+            + `Close this review with ${cancel}, then start a new renewal without --request-key.`, 2);
+    }
+    if (quoteGiven !== undefined && quoteGiven !== reviewed.quote.id) {
+        throw new CliError('idempotency_conflict', `That estimate is not this renewal's (its estimate is ${reviewed.quote.id}). Nothing was reserved or extended.`, 2);
+    }
+    let approved = options.approve === true && (!reviewed.quote.credit_approval_required || quoteGiven === reviewed.quote.id);
+    const interactive = tty(options);
+    emit('tool_renewal_quote', { ...reviewed, session_id: target.sessionId }, quoteText(target, reviewed));
+    if (!approved && interactive) {
+        approved = await selectOne(`Extend these tools by ${seconds(reviewed.additional_seconds)}?`, [
+            { value: false, label: 'Not now', detail: 'Nothing is reserved or extended. The review stays open until it is closed or its estimate expires.' },
+            { value: true, label: 'Extend them', detail: 'Reserves up to the estimate above and moves the end time. Same tools and data; nothing restarts.' },
+        ], signal);
+    }
+    if (!approved) {
+        throw new CliError('tool_change_consent_required', 'Nothing was reserved or extended. Show the human this estimate; after they approve it: '
+            + `${recovery} --usage-quote ${reviewed.quote.id} --approve-tool-change\nIf they decline, close the review: ${cancel} --approve-tool-change`, 2);
+    }
+    const creditApproval = await approveCredits([reviewed.quote], options, interactive, `${recovery} --usage-quote ${reviewed.quote.id} --approve-tool-change`);
+    let applied;
+    try {
+        applied = await retryTransient(() => applyRenewal(scope, { renewal: reviewed, signal, creditApproval }), { signal, attempts: 3 });
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw error;
+        // An unanswered approval may have landed: the renewal says, and nothing is applied or charged twice.
+        let recoveryState = 'read_failed';
+        const current = await getRenewal(scope, { batchId, renewalId: reviewed.id, signal: AbortSignal.timeout(RECOVER_MS) })
+            .catch(readError => {
+            if (readError instanceof CliError && readError.httpStatus === 404)
+                recoveryState = 'not_found';
+            return null;
+        });
+        if (!current || current.state === 'reviewed') {
+            if (error instanceof CliError && error.httpStatus !== null && !isTransient(error))
+                throw error;
+            renewalDiagnostic(emit, 'approval', error, current?.state === 'reviewed' ? 'still_reviewed' : recoveryState);
+            throw new CliError('tool_renewal_unconfirmed', `The approval was not confirmed. Check firedrill tools session ${target.sessionId} renewal ${reviewed.id}; `
+                + `if it is still reviewed, run ${recovery} --usage-quote ${reviewed.quote.id} --approve-tool-change. It is never charged twice.`);
+        }
+        applied = current;
+    }
+    emit('tool_renewal', applied, renewalText(target, applied)
+        + (applied.state === 'applied' ? `\nThe tools now run until ${terminalText(applied.new_expires_at)}. Check with firedrill tools session ${target.sessionId}.` : ''));
+}
+/** Each renewal verb's arguments and flags, checked before anything is read or sent. */
+export function checkRenewalArguments(verb, value, options) {
+    const takes = {
+        renew: ['seconds', 'request', 'quote', 'approve', 'approveCredits'], renewals: ['page'], renewal: [], 'cancel-renewal': ['approve'],
+        'renewal-request': [], 'withdraw-renewal': ['approve'],
+    };
+    const flags = { seconds: '--seconds', request: '--request-key', quote: '--usage-quote',
+        approve: '--approve-tool-change', approveCredits: '--approve-credits', page: '--page' };
+    const extra = Object.keys(flags)
+        .filter((flag) => options[flag] !== undefined && options[flag] !== false && !takes[verb]?.includes(flag));
+    if (extra.length)
+        throw new CliError('arguments_invalid', `tools session <session-id> ${verb} does not take ${extra.map((flag) => flags[flag]).join(', ')}.`, 2);
+    if (!RENEWAL_VERBS.has(verb) || (verb === 'renew' || verb === 'renewals') !== (value === undefined)) {
+        throw new CliError('arguments_invalid', 'Use tools session <session-id> renew --seconds <n>, renewals, renewal <renewal-id>, cancel-renewal <renewal-id>, '
+            + 'renewal-request <key> or withdraw-renewal <key>.', 2);
+    }
+}
+/**
+ * `tools session <session-id> renew --seconds <n> [--request-key <key>] [--usage-quote <quote-id>] [--approve-tool-change]
+ *  | renewals [--page <n>] | renewal <renewal-id> | cancel-renewal <renewal-id> [--approve-tool-change]
+ *  | renewal-request <key> | withdraw-renewal <key> [--approve-tool-change]`.
+ */
+export async function toolRenewalCommand(scope, target, verb, value, options, emit) {
+    checkRenewalArguments(verb, value, options);
+    const signal = options.signal;
+    const batchId = target.batch.id;
+    const session = `firedrill tools session ${target.sessionId}`;
+    if (verb === 'renew')
+        return renew(scope, target, options, emit);
+    if (verb === 'renewals') {
+        const page = await listRenewals(scope, { batchId, page: pageNumber(options.page), signal });
+        emit('tool_renewals', { session_id: target.sessionId, batch_id: batchId, ...page }, [
+            `Renewals of tool session ${target.sessionId}, page ${page.page} (${page.count} in all):`,
+            ...page.results.map((one) => `  ${one.id}  ${STATE_TEXT[one.state]}  +${seconds(one.additional_seconds)}, until ${terminalText(one.new_expires_at)}`
+                + `  ${terminalText(one.created_at)}`),
+            page.results.length ? null : '  none',
+            page.next ? `More: --page ${page.page + 1}` : null,
+            page.results.length ? `Read one: ${session} renewal <renewal-id>` : null,
+            `Extend the tools: ${session} renew --seconds <n>`,
+        ].filter((line) => line !== null).join('\n'));
+        return;
+    }
+    if (verb === 'renewal' || verb === 'cancel-renewal') {
+        const id = renewalId(value, 'renewal id');
+        const row = await getRenewal(scope, { batchId, renewalId: id, signal }).catch((error) => {
+            if (error instanceof CliError && error.httpStatus === 404) {
+                throw new CliError('tool_renewal_not_found', `That renewal is not one of this session's. List them with ${session} renewals.`, 2);
+            }
+            throw error;
+        });
+        if (verb === 'renewal' || row.state !== 'reviewed') {
+            emit('tool_renewal', row, renewalText(target, row) + (row.state === 'reviewed'
+                ? `\nApprove it: ${session} renew --request-key ${row.request_key}\nClose it unused: ${session} cancel-renewal ${row.id}`
+                : verb === 'cancel-renewal' ? `\nThis renewal is ${STATE_TEXT[row.state]}, so there is nothing to close; nothing was sent.` : ''));
+            return;
+        }
+        await consent('Close this unused renewal review?', 'Its estimate can no longer be approved. The tools keep their current end time.', `${session} cancel-renewal ${row.id}`, options);
+        // Closing is idempotent, and an applied extension is returned unchanged (never undone).
+        const closed = await retryTransient(() => cancelRenewal(scope, { batchId, renewalId: row.id, signal }), { signal, attempts: 3 }).catch(ownerOnly);
+        emit('tool_renewal', closed, renewalText(target, closed) + (closed.state === 'applied'
+            ? '\nIt had already been applied, so nothing was closed or undone.' : '\nClosed. Nothing was reserved or extended.'));
+        return;
+    }
+    const requestKey = renewalId(value, 'request key');
+    if (verb === 'renewal-request') {
+        const row = await recoverRenewal(scope, { batchId, requestKey, signal }).catch(mapWithdrawn(requestKey));
+        if (!row) {
+            emit('tool_renewal_request', { session_id: target.sessionId, batch_id: batchId, request_key: requestKey, state: 'not_found' }, `No renewal is recorded under request ${requestKey} yet. An unanswered request may still arrive.\n`
+                + `Continue it with ${session} renew --seconds <the original n> --request-key ${requestKey}, `
+                + `or, if the human decides it must never be reviewed, withdraw it with ${session} withdraw-renewal ${requestKey} (which undoes nothing).`);
+            return;
+        }
+        emit('tool_renewal', row, renewalText(target, row));
+        return;
+    }
+    await consent(`Withdraw renewal request ${requestKey}?`, 'If it has not arrived, it can never be reviewed. If it already arrived, it is shown instead; nothing is undone.', `${session} withdraw-renewal ${requestKey}`, options);
+    const result = await retryTransient(() => withdrawRenewal(scope, { batchId, requestKey, signal }), { signal, attempts: 3 }).catch(ownerOnly);
+    if (result.state === 'withdrawn') {
+        emit('tool_renewal_withdrawal', result, `Renewal request ${requestKey} is withdrawn: it can never be reviewed. Nothing else changed.`);
+        return;
+    }
+    emit('tool_renewal_withdrawal', result, `Renewal request ${requestKey} had already arrived, so it was not withdrawn and nothing was undone:\n`
+        + renewalText(target, result.receipt)
+        + (result.receipt.state === 'reviewed' ? `\nClose that review unused with ${session} cancel-renewal ${result.receipt.id}.` : ''));
+}