firedrill-run 2.2.5 → 3.0.0

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

@@ -0,0 +1,426 @@
+// `firedrill tools state <instance-id> ...`: the data of one running shared-pool
+// tool instance. Save a checkpoint of it, or change it through one of the
+// instance's own declared operations, under a request key printed before
+// anything is sent. A lost answer is read back by that key; when root has no
+// record of it yet the request stays unknown, and the human either replays the
+// same key or withdraws it explicitly. Withdrawing never undoes anything.
+// Snapshots (the baseline and each checkpoint) are listed here. A reset (from
+// the baseline) or fork (from any snapshot) is a new one-tool session: root
+// reviews it under a printed request key, quotes it, and admits it only with
+// the exact estimate the human approved. Nothing is admitted automatically.
+import { randomUUID } from 'node:crypto';
+import { approveCredits } from './credit-approval.js';
+import { CliError } from '../http.js';
+import { selectOne, terminalText } from '../prompts.js';
+import { requestInput } from '../request-input.js';
+import { errorCode, isTransient, jitteredInterval, retryTransient, sleep } from '../native/control-plane.js';
+import { getStateOperation, listStateOperations, listStateSnapshots, recoverCloneRequest, recoverStateOperation, requestClone, requestStateOperation, stateId, stateMatches, withdrawStateRequest, STATE_OPEN, } from '../native/standalone-state.js';
+import { admitStandaloneBatch, getStandaloneBatch, getStandaloneInstance, quoteStandaloneBatch, STANDALONE_ACTIVE, } from '../native/standalone-tools.js';
+import { amount } from './plan-apply.js';
+const ARGUMENTS_LIMIT = 64 * 1024;
+const FOLLOW_MS = 2_000;
+const FOLLOW_LIMIT_MS = 2 * 60_000;
+const RECOVER_MS = 15_000;
+/** Root's session length bounds (one minute to one year). */
+const CLONE_MIN_SECONDS = 60;
+const CLONE_MAX_SECONDS = 31_536_000;
+/** An estimate this close to expiry is not approved: admission would race it. */
+const QUOTE_MARGIN_MS = 60_000;
+const STATE_TEXT = {
+    pending: 'waiting to run',
+    effect_pending: 'running',
+    unknown: 'outcome not confirmed yet (Firedrill is confirming it; do not send it again under a new key)',
+    completed: 'completed',
+    cancelled: 'cancelled before it ran',
+};
+const tty = (options) => !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+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);
+}
+function operationText(row) {
+    const what = row.action === 'checkpoint' ? 'checkpoint' : `edit ${terminalText(row.operation ?? '')}`;
+    const result = row.result;
+    const detail = !result ? ''
+        : row.action === 'checkpoint' ? ` (snapshot ${result.snapshot_id})`
+            : ` (${[result.before_revision !== undefined && result.after_revision !== undefined ? `revision ${result.before_revision} -> ${result.after_revision}` : null,
+                result.outcome ? terminalText(result.outcome) : null, typeof result.status === 'number' ? `status ${result.status}` : null].filter(Boolean).join(', ')})`;
+    return `${row.id}  ${what}  ${STATE_TEXT[row.state] ?? terminalText(row.state)}${detail}  ${row.created_at}  request ${row.request_key}`;
+}
+function batchText(batch) {
+    return `Tool session ${batch.id} (${terminalText(batch.state)}), request ${batch.request_key}: `
+        + batch.instances.map((one) => `${terminalText(one.name)} instance ${one.id}`).join(', ');
+}
+/** The instance must be a shared-pool instance of this workspace; isolated tools keep their own state. */
+async function instanceOf(scope, instanceId, signal) {
+    try {
+        return await getStandaloneInstance(scope, { instanceId, signal });
+    }
+    catch (error) {
+        if (error instanceof CliError && error.httpStatus === 404) {
+            throw new CliError('tool_instance_not_found', 'No shared-pool tool instance with that id is in this workspace. State operations apply to shared-pool '
+                + 'instances (firedrill tools session <session-id> lists them); an isolated tool keeps its own state. Nothing was sent.', 2);
+        }
+        throw error;
+    }
+}
+const withdrawnError = (requestKey) => new CliError('native_tool_request_withdrawn', `Request ${requestKey} was withdrawn and can never run. Start a new request without --request-key.`, 2);
+/** A printed key given back, checked before anything is printed or sent; otherwise a new one. */
+const keyOf = (value) => value === undefined ? randomUUID() : stateId(value, 'request key');
+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);
+}
+/** Read an accepted operation back until root settles it, for a bounded time. */
+async function follow(scope, row, signal) {
+    const deadline = Date.now() + FOLLOW_LIMIT_MS;
+    let current = row;
+    while (STATE_OPEN.has(current.state) && Date.now() < deadline) {
+        if (!await sleep(jitteredInterval(FOLLOW_MS), signal))
+            break;
+        const operationId = current.id;
+        current = await retryTransient(() => getStateOperation(scope, { instanceId: row.instance_id, operationId, signal }), { signal, attempts: 4 });
+    }
+    return current;
+}
+/** `tools state <instance> checkpoint|edit ...`: one request under a printed key, replayed (never repeated) with --request-key. */
+async function send(scope, instance, request, command, options, emit) {
+    const requestKey = keyOf(options.request);
+    // An edit reaches here only after the human approved it, so its replay keeps that approval (a checkpoint takes none);
+    // a replay without it would stop for consent and print a retry the human might rerun under a new key.
+    const replay = `${command} --request-key ${requestKey}${request.action === 'edit' ? ' --approve-tool-change' : ''}`;
+    const read = `firedrill tools state ${instance.id} request ${requestKey}`;
+    const withdraw = `firedrill tools state ${instance.id} withdraw-request ${requestKey}`;
+    emit('tool_state_request', { instance_id: instance.id, request_key: requestKey, action: request.action,
+        operation: request.action === 'edit' ? request.operation : null }, `State request: ${requestKey}\nIf interrupted, read it with ${read}, `
+        + `or replay exactly this request with ${replay}. Do not send it again under a new key.`);
+    let row;
+    try {
+        row = await requestStateOperation(scope, { instanceId: instance.id, requestKey, request, signal: options.signal });
+    }
+    catch (error) {
+        if (errorCode(error) === 'native_tool_request_withdrawn')
+            throw withdrawnError(requestKey);
+        // Only an unanswered (or cancelled) request may have landed; a refusal or a bad local input is reported as it is.
+        if (!options.signal.aborted && !isTransient(error) && errorCode(error) !== 'native_response_unconfirmed')
+            throw error;
+        const found = await recoverStateOperation(scope, { instanceId: instance.id, requestKey, signal: AbortSignal.timeout(RECOVER_MS) })
+            .catch((recovery) => { if (errorCode(recovery) === 'native_tool_request_withdrawn')
+            throw withdrawnError(requestKey); return null; });
+        if (!found || !stateMatches(found, request)) {
+            throw new CliError('tool_state_unconfirmed', `The request was not confirmed. Read it with ${read}; replay it with ${replay}; `
+                + `or, if the human decides it must never run, withdraw it with ${withdraw} (which undoes nothing).`);
+        }
+        row = found;
+    }
+    const settled = await follow(scope, row, options.signal);
+    emit('tool_state_operation', settled, `${operationText(settled)}`
+        + (STATE_OPEN.has(settled.state) ? `\nNot settled yet. Check it with ${read}.` : '')
+        + (settled.state === 'completed' && settled.action === 'checkpoint' ? `\nSnapshots: firedrill tools state ${instance.id} snapshots` : ''));
+}
+function cloneSeconds(value) {
+    if (value === undefined)
+        return null;
+    if (!/^[1-9][0-9]{0,8}$/.test(value) || Number(value) < CLONE_MIN_SECONDS || Number(value) > CLONE_MAX_SECONDS) {
+        throw new CliError('tool_duration_invalid', `Use --seconds with a whole number from ${CLONE_MIN_SECONDS} to ${CLONE_MAX_SECONDS} (one year). Nothing was sent.`, 2);
+    }
+    return Number(value);
+}
+/** The instance's own baseline snapshot, which a reset starts from. */
+async function baselineOf(scope, instanceId, signal) {
+    {
+        const snapshots = await listStateSnapshots(scope, { instanceId, page: 1, kind: 'baseline', signal });
+        const baseline = snapshots.results.find((one) => one.kind === 'baseline');
+        if (baseline) {
+            if (!baseline.available)
+                throw new CliError('tool_snapshot_unavailable', 'This instance\'s baseline is no longer retained, so it cannot be reset. Nothing was sent.', 2);
+            return baseline.id;
+        }
+    }
+    throw new CliError('tool_snapshot_unavailable', `No baseline snapshot was found for this instance. List them with firedrill tools state ${instanceId} snapshots. Nothing was sent.`, 2);
+}
+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 cloneQuoteText(quotes) {
+    const [first, second] = quotes.quotes;
+    const money = (units, one) => amount(units, one.credit_scale, one.denomination);
+    const same = first.denomination === second.denomination && first.credit_scale === second.credit_scale;
+    const earliest = Date.parse(first.expires_at) <= Date.parse(second.expires_at) ? first.expires_at : second.expires_at;
+    return [
+        `Cloud-work estimate (maximum, reserved only once approved)${same ? `: ${money(first.maximum_units + second.maximum_units, first)}` : ', every part below:'}`,
+        `  shared pool preparation: up to ${money(first.maximum_units, first)}`,
+        `  shared pool running time: up to ${money(second.maximum_units, second)}`,
+        `Estimate expires: ${terminalText(earliest)}`,
+    ].join('\n');
+}
+/**
+ * `tools state <instance> reset|fork <snapshot-id> --seconds <n> [--request-key <key>] [--usage-quote <key>]
+ * [--approve-tool-change]`: root reviews the reset or fork as a new one-tool session under a printed request
+ * key (a rerun with that key continues the original, never a second review), quotes it, and admits it on the
+ * shared pool only with the exact estimate the human approved, through the batch's own quote and admit routes.
+ */
+async function startClone(scope, instanceId, action, snapshotArg, options, emit) {
+    const signal = options.signal;
+    const requestKey = keyOf(options.request);
+    const wanted = cloneSeconds(options.seconds);
+    if (options.quote !== undefined && options.request === undefined) {
+        throw new CliError('arguments_invalid', 'Use --usage-quote with the quote key and --request-key that were printed together. Nothing was sent.', 2);
+    }
+    const quoteGiven = options.quote === undefined ? undefined : stateId(options.quote, 'quote key');
+    const snapshotGiven = action === 'fork' ? stateId(snapshotArg, 'snapshot id') : null;
+    const recovery = `firedrill tools state ${instanceId} ${action}${snapshotGiven ? ` ${snapshotGiven}` : ''}${wanted ? ` --seconds ${wanted}` : ''} --request-key ${requestKey}`;
+    const read = `firedrill tools state ${instanceId} clone-request ${requestKey}`;
+    const withdraw = `firedrill tools state ${instanceId} withdraw-clone ${requestKey}`;
+    // A reset or fork already reviewed under this key is continued, never reviewed again.
+    let batch = options.request === undefined ? null : await recoverCloneRequest(scope, { instanceId, requestKey, signal }).catch((error) => {
+        if (errorCode(error) === 'native_tool_request_withdrawn')
+            throw withdrawnError(requestKey);
+        throw error;
+    });
+    if (batch && wanted !== null && batch.duration_seconds !== wanted) {
+        throw new CliError('idempotency_conflict', `That request was reviewed for ${seconds(batch.duration_seconds)}. Continue it without --seconds, or start a new one without --request-key.`, 2);
+    }
+    if (!batch) {
+        if (wanted === null)
+            throw new CliError('tool_duration_required', 'Use --seconds <n> to say how long the new tool session runs. Nothing was sent.', 2);
+        const instance = await instanceOf(scope, instanceId, signal);
+        const snapshotId = snapshotGiven ?? await baselineOf(scope, instance.id, signal);
+        emit('tool_clone_request', { instance_id: instance.id, action, snapshot_id: snapshotId, duration_seconds: wanted, request_key: requestKey }, `${action === 'reset' ? 'Reset' : 'Fork'} request: ${requestKey}\nIf interrupted, continue with ${recovery}. Do not start again under a new key.`);
+        try {
+            batch = await requestClone(scope, { instanceId: instance.id, requestKey, snapshotId, durationSeconds: wanted, action, signal });
+        }
+        catch (error) {
+            if (errorCode(error) === 'native_tool_request_withdrawn')
+                throw withdrawnError(requestKey);
+            // 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;
+            batch = await recoverCloneRequest(scope, { instanceId, requestKey, signal: AbortSignal.timeout(RECOVER_MS) }).catch(() => null);
+            if (!batch) {
+                throw new CliError('tool_clone_unconfirmed', `The 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 = batch;
+    if (reviewed.clone_source?.action !== action || reviewed.clone_source.source_instance_id !== instanceId
+        || (snapshotGiven !== null && reviewed.clone_source.source_snapshot_id !== snapshotGiven)
+        || (wanted !== null && reviewed.duration_seconds !== wanted)) {
+        throw new CliError('idempotency_conflict', 'This key belongs to a different original reset or fork. Read its original receipt before approving it. Nothing further was sent.', 2);
+    }
+    const sessionText = (current) => `${batchText(current)}\nWatch it: firedrill tools session ${current.id}`;
+    if (reviewed.state !== 'reviewed' || reviewed.stop_requested_at) {
+        // Already approved (or ended): shown as it is, never approved again.
+        emit('tool_session', reviewed, sessionText(reviewed));
+        return;
+    }
+    // Quoting reserves nothing. The same quote key replays the same estimate, so an approval given for that
+    // key admits exactly what the human saw; a new or different key is a new estimate that needs its own approval.
+    const quoteKey = quoteGiven ?? randomUUID();
+    const quotes = await retryTransient(() => quoteStandaloneBatch(scope, { batch: reviewed, quoteKey, signal }), { signal, attempts: 3 });
+    if (!quotes.quotes.every((one) => Date.parse(one.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 started. '
+            + `For a fresh estimate: ${recovery}. If the human no longer wants this ${action}, close the unapproved review: `
+            + `firedrill tools session ${reviewed.id} stop --approve-tool-change`, 2);
+    }
+    const notice = quoteGiven !== undefined && !quotes.replayed ? 'No estimate was quoted for this session under that quote key, so this is a new one. ' : '';
+    let approved = options.approve === true && (!quotes.quotes.some(quote => quote.credit_approval_required) || (quoteGiven !== undefined && quotes.replayed));
+    const interactive = tty(options);
+    if (!approved && interactive)
+        process.stderr.write(`${batchText(reviewed)}\n`);
+    emit('tool_clone_quote', quotes, `${notice}${cloneQuoteText(quotes)}`);
+    if (!approved && interactive) {
+        approved = await selectOne(`Start this ${action} for ${seconds(reviewed.duration_seconds)}?`, [
+            { value: false, label: 'Not now', detail: 'Nothing is reserved or started.' },
+            { value: true, label: `Start the ${action}`, detail: 'Reserves up to the estimate above. The tool runs on the shared pool in the cloud, not on this machine.' },
+        ], signal);
+    }
+    if (!approved) {
+        throw new CliError('tool_change_consent_required', `${notice}Nothing was reserved or started. Show the human this estimate; after they approve it: `
+            + `${recovery} --usage-quote ${quoteKey} --approve-tool-change`, 2);
+    }
+    const creditApproval = await approveCredits(quotes.quotes, options, interactive, `${recovery} --usage-quote ${quoteKey} --approve-tool-change`);
+    let admitted;
+    try {
+        admitted = await retryTransient(() => admitStandaloneBatch(scope, { quotes, signal, creditApproval }), { signal, attempts: 3 });
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw error;
+        // An unanswered approval may have landed: the session says, and nothing is admitted twice.
+        const current = await getStandaloneBatch(scope, { batchId: quotes.batch_id, signal: AbortSignal.timeout(RECOVER_MS) }).catch(() => null);
+        if (!current || current.original_digest !== quotes.batch_digest || current.state === 'reviewed') {
+            if (error instanceof CliError && error.httpStatus !== null && !isTransient(error))
+                throw error;
+            throw new CliError('tool_start_unconfirmed', `The approval was not confirmed. Check firedrill tools session ${quotes.batch_id}; `
+                + `if it is still reviewed, run ${recovery} --usage-quote ${quoteKey} --approve-tool-change.`);
+        }
+        admitted = current;
+    }
+    emit('tool_session', admitted, sessionText(admitted));
+}
+/** Withdraw a state or reset/fork request after the human's explicit approval; root returns the original instead when it already landed. */
+async function withdraw(scope, instanceId, requestKey, kind, options, emit) {
+    const verb = kind === 'state' ? 'withdraw-request' : 'withdraw-clone';
+    await consent(`Withdraw request ${requestKey}?`, 'If it has not arrived, it can never run. If it already arrived, it is shown instead; nothing is undone.', `firedrill tools state ${instanceId} ${verb} ${requestKey}`, options);
+    const result = await retryTransient(() => withdrawStateRequest(scope, { instanceId, requestKey, kind, signal: options.signal }), { signal: options.signal, attempts: 3 });
+    if (result.state === 'withdrawn') {
+        emit('tool_state_withdrawal', result, `Request ${requestKey} is withdrawn: it can never run. Nothing else changed.`);
+        return;
+    }
+    const receipt = result.receipt;
+    emit('tool_state_withdrawal', result, `Request ${requestKey} had already arrived, so it was not withdrawn and nothing was undone:\n`
+        + ('action' in receipt ? operationText(receipt) : batchText(receipt)));
+}
+/**
+ * `tools state <instance> [checkpoint | edit <operation> --file <arguments.json> | operation <id> | snapshots
+ *  | request <key> | withdraw-request <key> | clone-request <key> | withdraw-clone <key>]`.
+ */
+export async function toolStateCommand(scope, args, options, emit) {
+    const [instanceArg, verb, target, ...rest] = args;
+    const usage = 'Use tools state <instance-id> [checkpoint | edit <operation> --file <arguments.json> | operation <operation-id> | snapshots '
+        + '| reset --seconds <n> | fork <snapshot-id> --seconds <n> | request <key> | withdraw-request <key> | clone-request <key> | withdraw-clone <key>].';
+    if (rest.length)
+        throw new CliError('arguments_invalid', usage, 2);
+    const instanceId = stateId(instanceArg, 'tool instance id');
+    const signal = options.signal;
+    const takes = (allowed) => {
+        const given = ['file', 'request', 'approve', 'approveCredits', 'page', 'seconds', 'quote']
+            .filter((flag) => options[flag] !== undefined && options[flag] !== false && !allowed.includes(flag));
+        if (given.length)
+            throw new CliError('arguments_invalid', `${usage} --request-key is for checkpoint, edit, reset and fork, --file for edit, `
+                + '--seconds and --usage-quote for reset and fork, --approve-tool-change for edit, reset, fork and withdrawals, --page for lists.', 2);
+    };
+    if (verb === undefined || verb === 'snapshots') {
+        takes(['page']);
+        if (target !== undefined)
+            throw new CliError('arguments_invalid', usage, 2);
+        const page = pageNumber(options.page);
+        if (verb === 'snapshots') {
+            const snapshots = await listStateSnapshots(scope, { instanceId, page, signal });
+            emit('tool_state_snapshots', snapshots, [
+                `Snapshots of instance ${instanceId}, page ${snapshots.page ?? page ?? 1} (${snapshots.count} in all):`,
+                ...snapshots.results.map((one) => `  ${one.id}  ${terminalText(one.kind)}  ${one.created_at}${one.available ? '' : '  (no longer available)'}`),
+                snapshots.results.length ? null : '  none',
+                snapshots.next ? `More: --page ${(snapshots.page ?? page ?? 1) + 1}` : null,
+                `A new tool session from the baseline: firedrill tools state ${instanceId} reset --seconds <n>`,
+                `A new tool session from a snapshot: firedrill tools state ${instanceId} fork <snapshot-id> --seconds <n>`,
+                'Either one is reviewed and quoted first, and starts only after the human approves the estimate; this instance is not changed.',
+            ].filter((line) => line !== null).join('\n'));
+            return;
+        }
+        const operations = await listStateOperations(scope, { instanceId, page, signal });
+        emit('tool_state_operations', operations, [
+            `State operations on instance ${instanceId}, newest first, page ${operations.page ?? page ?? 1} (${operations.count} in all):`,
+            ...operations.results.map((one) => `  ${operationText(one)}`),
+            operations.results.length ? null : '  none',
+            operations.next ? `More: --page ${(operations.page ?? page ?? 1) + 1}` : null,
+            `Save a checkpoint: firedrill tools state ${instanceId} checkpoint`,
+            `Change its data through one of its operations: firedrill tools state ${instanceId} edit <operation> --file <arguments.json>`,
+        ].filter((line) => line !== null).join('\n'));
+        return;
+    }
+    if (verb === 'checkpoint') {
+        takes(['request']);
+        if (target !== undefined)
+            throw new CliError('arguments_invalid', usage, 2);
+        const instance = await instanceOf(scope, instanceId, signal);
+        if (options.request === undefined && instance.state !== STANDALONE_ACTIVE) {
+            throw new CliError('tool_instance_inactive', `This instance is ${terminalText(instance.state)}, not running, so its data cannot be saved now. Nothing was sent.`, 2);
+        }
+        await send(scope, instance, { action: 'checkpoint' }, `firedrill tools state ${instance.id} checkpoint`, options, emit);
+        return;
+    }
+    if (verb === 'edit') {
+        takes(['request', 'file', 'approve']);
+        if (!target || target.length > 200)
+            throw new CliError('arguments_invalid', `Use tools state ${instanceId} edit <operation> --file <arguments.json>.`, 2);
+        if (options.file === undefined)
+            throw new CliError('arguments_invalid', 'Use --file <arguments.json> (or - for stdin) with the operation\'s JSON arguments. Nothing was sent.', 2);
+        const instance = await instanceOf(scope, instanceId, signal);
+        if (!instance.operations.includes(target)) {
+            throw new CliError('tool_operation_unknown', `This instance does not declare ${terminalText(target)}. Its operations: ${instance.operations.map(terminalText).join(', ')}. Nothing was sent.`, 2);
+        }
+        if (options.request === undefined && instance.state !== STANDALONE_ACTIVE) {
+            throw new CliError('tool_instance_inactive', `This instance is ${terminalText(instance.state)}, not running, so its data cannot be changed now. Nothing was sent.`, 2);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(await requestInput(options.file, signal, ARGUMENTS_LIMIT));
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            throw new CliError('request_file_invalid', 'The arguments file is not valid JSON. Nothing was sent.', 2);
+        }
+        const command = `firedrill tools state ${instance.id} edit ${target} --file ${options.file === '-' ? '<the same arguments file>' : options.file}`;
+        // A replay's approval retry keeps its original key: without it the rerun would mint a new key and could apply the edit twice.
+        const retry = options.request === undefined ? command : `${command} --request-key ${stateId(options.request, 'request key')}`;
+        if (!options.approve && tty(options)) {
+            process.stderr.write(`${terminalText(instance.name)} (instance ${instance.id}): run ${terminalText(target)} against its data with the arguments in the file.\n`);
+        }
+        await consent(`Change this tool's data with ${terminalText(target)}?`, 'The tool records the change; it is not undone automatically.', retry, options);
+        await send(scope, instance, { action: 'edit', operation: target, arguments: parsed }, command, options, emit);
+        return;
+    }
+    if (verb === 'reset' || verb === 'fork') {
+        takes(['request', 'seconds', 'quote', 'approve', 'approveCredits']);
+        if (verb === 'reset' && target !== undefined)
+            throw new CliError('arguments_invalid', `Use tools state ${instanceId} reset --seconds <n>; a reset always starts from the baseline.`, 2);
+        if (verb === 'fork' && target === undefined)
+            throw new CliError('arguments_invalid', `Use tools state ${instanceId} fork <snapshot-id> --seconds <n> (snapshot ids from tools state ${instanceId} snapshots).`, 2);
+        await startClone(scope, instanceId, verb, target, options, emit);
+        return;
+    }
+    if (verb === 'operation') {
+        takes([]);
+        const operationId = stateId(target, 'state operation id');
+        const row = await getStateOperation(scope, { instanceId, operationId, signal }).catch((error) => {
+            if (error instanceof CliError && error.httpStatus === 404) {
+                throw new CliError('tool_state_operation_not_found', `That operation is not on this instance. List them with firedrill tools state ${instanceId}.`, 2);
+            }
+            throw error;
+        });
+        emit('tool_state_operation', row, operationText(row));
+        return;
+    }
+    if (verb === 'request' || verb === 'clone-request') {
+        takes([]);
+        const requestKey = stateId(target, 'request key');
+        const unknown = (what) => `Firedrill has no ${what} under ${requestKey} for you on this instance yet. That is not proof it never arrives: `
+            + `replay it with the same --request-key, or withdraw it with firedrill tools state ${instanceId} ${verb === 'request' ? 'withdraw-request' : 'withdraw-clone'} ${requestKey} `
+            + '(which undoes nothing).';
+        try {
+            if (verb === 'request') {
+                const row = await recoverStateOperation(scope, { instanceId, requestKey, signal });
+                emit('tool_state_request_status', { request_key: requestKey, operation: row }, row ? operationText(row) : unknown('state request'));
+            }
+            else {
+                const batch = await recoverCloneRequest(scope, { instanceId, requestKey, signal });
+                emit('tool_state_clone_request', { request_key: requestKey, session: batch }, batch ? batchText(batch) : unknown('reset or fork request'));
+            }
+        }
+        catch (error) {
+            if (errorCode(error) !== 'native_tool_request_withdrawn')
+                throw error;
+            emit('tool_state_request_status', { request_key: requestKey, withdrawn: true }, `Request ${requestKey} was withdrawn; it can never run.`);
+        }
+        return;
+    }
+    if (verb === 'withdraw-request' || verb === 'withdraw-clone') {
+        takes(['approve']);
+        await withdraw(scope, instanceId, stateId(target, 'request key'), verb === 'withdraw-request' ? 'state' : 'clone', options, emit);
+        return;
+    }
+    throw new CliError('arguments_invalid', usage, 2);
+}

package/dist/cli/src/simple/tools-author.js

@@ -0,0 +1,222 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+import { CliError } from '../http.js';
+import { terminalText } from '../prompts.js';
+import { toolsCommand } from '../tools.js';
+// Client-side reading bound only. The cloud package inspection is authoritative
+// for capacity, engine preflight, capability references and credential screening.
+const MAX_JSON_BYTES = 2 * 1024 * 1024;
+const SLUG = /^[a-z][a-z0-9_-]{0,79}$/;
+const NAME = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;
+const VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.-]+)?$/;
+const CONTROL = /[\u0000-\u001f\u007f]/;
+const PRIVATE_BUNDLE_ROOTS = new Set(['scenarios', 'checks', 'handlers', 'simulator_prompt.md', 'sub_goals.json', 'generic-harness']);
+async function readObject(path, label, signal) {
+    let info;
+    try {
+        info = await lstat(path);
+    }
+    catch {
+        throw new CliError('tool_package_file_missing', `${label} was not found.`, 2);
+    }
+    if (!info.isFile() || info.isSymbolicLink() || info.size > MAX_JSON_BYTES)
+        throw new CliError('tool_package_file_invalid', `${label} must be a regular file of at most ${MAX_JSON_BYTES} bytes.`, 2);
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const bytes = await file.readFile({ signal });
+        const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error();
+        return value;
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw error;
+        throw new CliError('tool_package_file_invalid', `${label} is not a UTF-8 JSON object.`, 2);
+    }
+    finally {
+        await file.close();
+    }
+}
+const text = (value, maximum, empty = false) => typeof value === 'string' && value.length <= maximum && (empty || !!value.trim()) && !CONTROL.test(value);
+const route = (value) => typeof value === 'string' && value.length <= 2048 && value.startsWith('/') && !value.startsWith('//')
+    && !/[\\?#%]/.test(value) && !/[\u0000- \u007f]/.test(value) && !value.split('/').some(part => part === '.' || part === '..');
+/** Structural mirror of the tool.json rules; mirrors field names, not engine semantics. */
+function contractProblems(value) {
+    const problems = [];
+    const add = (path, message) => { problems.push({ path, message }); };
+    const required = ['schema', 'key', 'version', 'name', 'description', 'services'];
+    for (const field of required)
+        if (!(field in value))
+            add(field, 'Required field is missing.');
+    for (const field of Object.keys(value))
+        if (![...required, 'state'].includes(field))
+            add(field, 'Unknown top-level field.');
+    if (value.schema !== 'firedrill.tool-package.v1')
+        add('schema', 'Use firedrill.tool-package.v1.');
+    if (typeof value.key !== 'string' || !SLUG.test(value.key))
+        add('key', 'Use lowercase letters, digits, _ or -, starting with a letter.');
+    if (typeof value.version !== 'string' || value.version.length > 80 || !VERSION.test(value.version))
+        add('version', 'Use a semantic version such as 1.0.0.');
+    if (!text(value.name, 120))
+        add('name', 'Use a non-empty name of up to 120 characters.');
+    if (!text(value.description, 2000, true))
+        add('description', 'Use a description of up to 2000 characters.');
+    const services = value.services;
+    if (!Array.isArray(services) || !services.length) {
+        add('services', 'Declare at least one service.');
+        return problems;
+    }
+    const keys = new Set();
+    services.forEach((service, index) => {
+        const at = `services[${index}]`;
+        if (!service || typeof service !== 'object' || Array.isArray(service)) {
+            add(at, 'Each service must be an object.');
+            return;
+        }
+        const row = service;
+        const fields = Object.keys(row).sort().join(',');
+        if (fields !== 'key,name,operations,surface')
+            add(at, 'Use exactly key, name, operations and surface.');
+        if (typeof row.key !== 'string' || !SLUG.test(row.key))
+            add(`${at}.key`, 'Use a lowercase service key.');
+        else if (keys.has(row.key))
+            add(`${at}.key`, 'Service keys must be unique.');
+        else
+            keys.add(row.key);
+        if (!text(row.name, 120))
+            add(`${at}.name`, 'Use a non-empty name of up to 120 characters.');
+        if (row.surface !== null && row.surface !== undefined) {
+            const surface = row.surface;
+            if (typeof surface !== 'object' || Array.isArray(surface) || Object.keys(surface).sort().join(',') !== 'capability,path'
+                || typeof surface.capability !== 'string' || !route(surface.path))
+                add(`${at}.surface`, 'Use null or { capability, path } with an absolute path.');
+        }
+        if (!Array.isArray(row.operations) || !row.operations.length) {
+            add(`${at}.operations`, 'Declare at least one operation.');
+            return;
+        }
+        const names = new Set();
+        row.operations.forEach((operation, position) => {
+            const op = `${at}.operations[${position}]`;
+            if (!operation || typeof operation !== 'object' || Array.isArray(operation)) {
+                add(op, 'Each operation must be an object.');
+                return;
+            }
+            const item = operation;
+            const allowed = ['name', 'description', 'effect', 'input_schema', 'output_schema', 'transport'];
+            for (const field of allowed)
+                if (!(field in item))
+                    add(`${op}.${field}`, 'Required field is missing.');
+            for (const field of Object.keys(item))
+                if (![...allowed, 'mcp_aliases'].includes(field))
+                    add(`${op}.${field}`, 'Unknown operation field.');
+            if (typeof item.name !== 'string' || !NAME.test(item.name))
+                add(`${op}.name`, 'Use a letter followed by letters, digits, _, . or -.');
+            else if (names.has(item.name))
+                add(`${op}.name`, 'Operation names must be unique within a service.');
+            else
+                names.add(item.name);
+            if (!text(item.description, 2000, true))
+                add(`${op}.description`, 'Use a description of up to 2000 characters.');
+            if (!['none', 'read', 'write', 'mixed'].includes(item.effect))
+                add(`${op}.effect`, 'Use none, read, write or mixed.');
+            if (!item.input_schema || typeof item.input_schema !== 'object' || Array.isArray(item.input_schema))
+                add(`${op}.input_schema`, 'Use a JSON schema object.');
+            const transport = item.transport;
+            if (!transport || typeof transport !== 'object' || Array.isArray(transport) || !['http', 'mcp'].includes(transport.kind)
+                || typeof transport.capability !== 'string') {
+                add(`${op}.transport`, 'Use an http or mcp transport with a capability name.');
+                return;
+            }
+            if (transport.kind === 'mcp' && (Object.keys(transport).sort().join(',') !== 'capability,kind,path,tool'
+                || typeof transport.tool !== 'string' || !NAME.test(transport.tool) || !route(transport.path)))
+                add(`${op}.transport`, 'An mcp transport uses exactly kind, capability, path and tool.');
+        });
+    });
+    return problems;
+}
+async function validate(directory, signal) {
+    const root = resolve(directory);
+    const info = await lstat(root).catch(() => null);
+    if (!info?.isDirectory())
+        throw new CliError('tool_package_directory_invalid', 'Choose the tool package directory that contains tool.json.', 2);
+    const contract = await readObject(join(root, 'tool.json'), 'tool.json', signal);
+    const manifest = await readObject(join(root, 'bundle', 'manifest.json'), 'bundle/manifest.json', signal);
+    const problems = contractProblems(contract);
+    if (Array.isArray(manifest.processes))
+        manifest.processes.forEach((process, index) => {
+            if (!process || typeof process !== 'object' || Array.isArray(process) || (process.kind ?? 'source') !== 'source')
+                return;
+            const path = process.working_directory;
+            const parts = typeof path === 'string' ? path.split('/').filter(part => part !== '' && part !== '.') : [];
+            if (!parts.length || parts.includes('..') || PRIVATE_BUNDLE_ROOTS.has(parts[0]))
+                problems.push({ path: `bundle/manifest.json.processes[${index}].working_directory`,
+                    message: 'Use a dedicated executable directory such as app, not the bundle root or private assessment directories.' });
+        });
+    const extra = (await readdir(root)).filter(name => !['tool.json', 'bundle'].includes(name)).sort();
+    return { directory: root, problems,
+        warnings: extra.length ? [`Not part of the package archive: ${extra.join(', ')}. The archive root holds only tool.json and bundle/.`] : [] };
+}
+export async function toolsAuthorCommand(args, options, emit) {
+    const action = args[0];
+    if (action === 'init') {
+        if (args.length > 2 || options.file !== undefined || options.upload || options.request !== undefined)
+            throw new CliError('arguments_invalid', 'Use firedrill tools init [directory]. Nothing is uploaded.', 2);
+        const root = resolve(args[1] ?? '.');
+        await mkdir(root, { recursive: true, mode: 0o755 });
+        const derived = basename(root).toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^[^a-z]+/, '').slice(0, 80);
+        const contract = { schema: 'firedrill.tool-package.v1', key: SLUG.test(derived) ? derived : 'custom-tool', version: '0.1.0',
+            name: 'Custom tool', description: '', services: [] };
+        let file;
+        try {
+            file = await open(join(root, 'tool.json'), 'wx', 0o644);
+        }
+        catch {
+            throw new CliError('tool_package_exists', 'tool.json already exists in this directory. Nothing was changed.', 2);
+        }
+        try {
+            await file.writeFile(JSON.stringify(contract, null, 2) + '\n');
+        }
+        finally {
+            await file.close();
+        }
+        // Only after tool.json was created exclusively, so an existing package is left untouched.
+        await mkdir(join(root, 'bundle'), { recursive: true, mode: 0o755 });
+        await mkdir(join(root, 'bundle', 'app'), { recursive: true, mode: 0o755 });
+        emit('tool_package_initialized', { directory: root, files: ['tool.json', 'bundle/', 'bundle/app/'], uploaded: false }, [`Created ${terminalText(join(root, 'tool.json'))} and bundle/.`,
+            'Declare at least one service in tool.json and add the process bundle with bundle/manifest.json.',
+            'Put executable files in bundle/app/ and use working_directory: "app". Never use the bundle root.',
+            'Then run firedrill tools validate and firedrill tools push <package.zip>. Nothing was uploaded.'].join('\n'));
+        return;
+    }
+    if (action === 'validate') {
+        if (args.length > 2 || options.file !== undefined || options.upload || options.request !== undefined)
+            throw new CliError('arguments_invalid', 'Use firedrill tools validate [directory]. Nothing is uploaded.', 2);
+        const result = await validate(args[1] ?? '.', options.signal);
+        const valid = !result.problems.length;
+        emit('tool_package_validation', { ...result, valid, scope: 'structural', uploaded: false }, [
+            valid ? 'tool.json and bundle/manifest.json passed local structural checks.' : `${result.problems.length} problems found:`,
+            ...result.problems.map(one => `  ${terminalText(one.path)}: ${one.message}`), ...result.warnings.map(terminalText),
+            'Capability references, engine preflight and capacity are checked by the cloud inspection after push.'
+        ].join('\n'));
+        if (!valid)
+            throw new CliError('tool_package_invalid', 'The tool package has structural problems. Nothing was uploaded.', 1);
+        return;
+    }
+    if (action === 'push') {
+        if (args.length > 2 || args[1] !== undefined && options.file !== undefined)
+            throw new CliError('arguments_invalid', 'Use firedrill tools push <package.zip> or --file <package.zip>.', 2);
+        const path = args[1] ?? options.file;
+        if (!path)
+            throw new CliError('tool_package_file_required', 'Use firedrill tools push <package.zip>. No file was read or uploaded.', 2);
+        const info = await lstat(resolve(path)).catch(() => null);
+        if (info?.isDirectory())
+            throw new CliError('tool_package_archive_required', 'Create a ZIP whose root holds tool.json and bundle/, then push that file. Nothing was uploaded.', 2);
+        await toolsCommand(['import'], { json: options.json, workspace: options.workspace, openBrowser: options.openBrowser,
+            signal: options.signal, file: path, upload: options.upload, request: options.request }, emit);
+        return;
+    }
+    throw new CliError('arguments_invalid', 'Use firedrill tools init|validate|push.', 2);
+}