firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/dependency-preparation.js

@@ -0,0 +1,239 @@
+import { randomUUID } from 'node:crypto';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { requestInput } from './request-input.js';
+import { choosePaged } from './configuration.js';
+import { compatibilityPageMatches, protocolProfileLines } from '../../contracts/dependency-protocol-contracts.js';
+import { dependencyDecisionCanonical, dependencyDecisionDigest, dependencyDecisionMatches, dependencyDecisionReceiptMatches } from '../../contracts/dependency-decision-contracts.js';
+const actions = new Set(['prepare', 'preparations', 'preparation', 'preparation-decision', 'choose-preparation', 'continue-preparation', 'cancel-preparation', 'compatibility']);
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const interactive = (options) => !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+const invalid = () => new CliError('dependency_response_unconfirmed', 'The dependency response could not be confirmed. Inspect the original preparation before submitting a different decision.');
+const sha = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+export const isDependencyPreparationAction = (action) => !!action && actions.has(action);
+function preparation(raw, scope) {
+    if (!object(raw) || raw.schema !== 'firedrill.dependency-preparation.v1' || raw.world_id !== scope.world || raw.workspace_id !== scope.workspace
+        || typeof raw.service_name !== 'string' || typeof raw.state !== 'string' || typeof raw.configuration_changed !== 'boolean'
+        || typeof raw.generated_authoring_supported !== 'boolean' || typeof raw.catalog_scan_complete !== 'boolean'
+        || !Array.isArray(raw.unresolved_semantics) || raw.unresolved_semantics.some(one => typeof one !== 'string')
+        || !Array.isArray(raw.candidates) || raw.candidates.length > 10)
+        throw invalid();
+    for (const key of ['id', 'actor_id', 'service_id', 'request_key'])
+        identifier(String(raw[key]));
+    for (const one of raw.candidates)
+        if (!object(one) || !sha(one.candidate_id) || typeof one.name !== 'string' || typeof one.version !== 'string'
+            || typeof one.all_declared_operations_match !== 'boolean' || !object(one.counts)
+            || Object.values(one.counts).some(count => typeof count !== 'number' || !Number.isSafeInteger(count) || count < 0))
+            throw invalid();
+    return raw;
+}
+function summary(value) {
+    return `${terminalText(value.service_name)}: ${terminalText(value.state)}\nPreparation: ${value.id}\n`
+        + value.candidates.map(one => `${one.candidate_id}  ${terminalText(one.name)} ${terminalText(one.version)}  ${one.counts.declaration_match ?? 0} matching operation declarations${one.all_declared_operations_match ? '' : ' (partial)'}`).join('\n')
+        + (value.problem ? `\n${terminalText(value.problem)}` : '')
+        + (value.configuration_changed ? '\nConnection settings changed. Request a current review before approving.' : '')
+        + '\nNo target run or real-account access is started by this preparation.';
+}
+function decisionBody(raw) {
+    if (!dependencyDecisionMatches(raw))
+        throw new CliError('dependency_decision_invalid', 'Use the exact catalog/generated decision with acknowledgement, continue with its original continuation_digest, or withdraw. No credentials or free text belong in this file.', 2);
+    return raw;
+}
+export async function dependencyPreparationCommand(args, options, output, selected) {
+    const action = args[0];
+    if (!isDependencyPreparationAction(action) || args.length > (['compatibility', 'preparation-decision'].includes(action) ? 3 : action === 'preparations' ? 1 : 2)
+        || !['choose-preparation', 'continue-preparation', 'cancel-preparation'].includes(action) && options.file)
+        throw new CliError('arguments_invalid', 'Use connections preparation-decision <id> <decision-digest> to read the original decision, or prepare, preparations, preparation, choose-preparation, continue-preparation, cancel-preparation or compatibility.', 2);
+    const scope = selected ?? await selectedWorld({ ...options, interactive: interactive(options) });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const page = options.page ?? '1';
+    if (!/^[1-9][0-9]{0,8}$/.test(page) || (options.search ?? '').length > 200)
+        throw new CliError('arguments_invalid', 'Choose a positive page and a short search.', 2);
+    const base = scope.prefix + '/dependency-preparation';
+    async function readDecision(preparation, digest, expected) {
+        const value = await api(`${base}/${preparation}/decisions/${digest}`, auth);
+        if (!dependencyDecisionReceiptMatches(value, { actor: scope.owner, workspace: scope.workspace, world: scope.world, preparation }, digest)
+            || expected && value.action !== null && value.action !== expected.action)
+            throw invalid();
+        return value;
+    }
+    const receiptSummary = (value) => value.state === 'accepted'
+        ? `The original decision was accepted (${value.accepted_state}). Preparation may have progressed since then.`
+        : value.state === 'not_observed' ? 'No acceptance is recorded yet. A delayed request may still arrive. Continue only with the exact original decision file.'
+            : 'The original decision history is unavailable. Keep its digest. Do not replace an uncertain decision.';
+    async function freshReviewGuidance(preparationId) {
+        const inspect = `firedrill connections preparation ${preparationId} --world ${scope.world} --workspace ${scope.workspace}`;
+        let original;
+        try {
+            original = preparation(await api(`${base}/${preparationId}`, auth), scope);
+            if (original.id !== preparationId)
+                throw invalid();
+        }
+        catch (error) {
+            if (error instanceof CliError && error.httpStatus === 404)
+                return { data: { preparation_id: preparationId, service_id: null,
+                        preparation_state: null, inspect_command: inspect, fresh_review_command: null },
+                    readable: 'The original preparation is no longer available. Keep its decision reference; no replacement was started.' };
+            throw error;
+        }
+        const active = ['queued', 'scanning', 'adopting'].includes(original.state);
+        const fresh = active ? null : `firedrill connections prepare ${original.service_id} --world ${scope.world} --workspace ${scope.workspace}`;
+        return { data: { preparation_id: preparationId, service_id: original.service_id, preparation_state: original.state,
+                inspect_command: inspect, fresh_review_command: fresh },
+            readable: `Original preparation: ${preparationId}\nService: ${original.service_id}\nInspect: ${inspect}\n`
+                + (active
+                    ? 'The original review or adoption is still active. Resolve its status before starting a fresh compatibility review; do not race it with another catalog choice.'
+                    : `If current connection access permits it, request a fresh read-only compatibility review: ${fresh}\nThis does not clear the original decision or approve a catalog/generated choice.`) };
+    }
+    async function outputReceipt(value) {
+        output('dependency_decision_receipt', value, receiptSummary(value));
+        if (value.state === 'unavailable') {
+            const guidance = await freshReviewGuidance(value.preparation_id);
+            output('dependency_preparation_recovery', guidance.data, guidance.readable);
+        }
+    }
+    if (action === 'preparation-decision') {
+        const preparationId = identifier(args[1]);
+        if (!sha(args[2]))
+            throw new CliError('arguments_invalid', 'Use connections preparation-decision <preparation-id> <original-decision-digest>.', 2);
+        const value = await readDecision(preparationId, args[2]);
+        await outputReceipt(value);
+        return;
+    }
+    if (action === 'preparations') {
+        const query = new URLSearchParams({ page, q: options.search ?? '', current: 'true' });
+        if (options.request)
+            query.set('request_key', identifier(options.request));
+        const raw = await api(`${base}?${query}`, auth);
+        if (!object(raw) || !Array.isArray(raw.results) || raw.results.length > 100 || !Number.isSafeInteger(raw.count))
+            throw invalid();
+        const rows = raw.results.map(one => preparation(one, scope));
+        output('dependency_preparations', { ...raw, results: rows }, (rows.map(one => `${one.id}  ${terminalText(one.service_name)}  ${terminalText(one.state)}`).join('\n') || 'No matching dependency preparations.') + `\nPage ${raw.page}, ${raw.count} records.`);
+        return;
+    }
+    if (action === 'prepare') {
+        const key = options.request ? identifier(options.request) : randomUUID();
+        if (options.request) {
+            const retained = await api(`${base}?request_key=${key}`, auth);
+            if (!object(retained) || !Array.isArray(retained.results) || retained.results.length > 1)
+                throw invalid();
+            if (retained.results.length) {
+                const original = preparation(retained.results[0], scope);
+                if (args[1] && original.service_id !== identifier(args[1]))
+                    throw new CliError('idempotency_conflict', 'This original request belongs to another dependency.', 2);
+                output('dependency_preparation', original, summary(original));
+                return;
+            }
+        }
+        const service = args[1] ? identifier(args[1]) : interactive(options)
+            ? (await choosePaged('Simulated connection', scope.prefix + '/dependencies?mode=simulated', scope, options, one => ({ label: one.name })))?.id : null;
+        if (!service)
+            throw new CliError('dependency_required', 'Choose a service with connections prepare <service-id>. Select simulated mode before requesting this review.', 2);
+        const current = await api(`${scope.prefix}/dependencies/${identifier(service)}`, auth);
+        if (!object(current) || !object(current.dependency) || current.dependency.id !== service || current.dependency.mode !== 'simulated'
+            || !Number.isSafeInteger(current.configuration_revision) || !Number.isSafeInteger(current.dependency.service_revision))
+            throw new CliError('dependency_simulation_choice_required', 'Select simulated mode for this exact current service before requesting preparation.', 2);
+        const body = { service_id: service, service_revision: current.dependency.service_revision, configuration_revision: current.configuration_revision };
+        output('dependency_preparation_intent', { request_key: key, world_id: scope.world, body }, `Original request: ${key}\nThis compares declarations only. Keep --request-key ${key} for recovery.`);
+        const value = preparation(await api(base, { ...auth, method: 'POST', body, idempotencyKey: key }), scope);
+        output('dependency_preparation', value, summary(value));
+        return;
+    }
+    const id = identifier(args[1]);
+    let originalBody;
+    if (options.file) {
+        originalBody = decisionBody(JSON.parse(await requestInput(options.file, options.signal, 8192)));
+        if (action === 'continue-preparation' && originalBody.action !== 'continue'
+            || action === 'cancel-preparation' && originalBody.action !== 'withdraw'
+            || action === 'choose-preparation' && !['catalog', 'generated'].includes(originalBody.action))
+            throw new CliError('dependency_decision_invalid', 'The decision file does not match this preparation command.', 2);
+        const original = await readDecision(id, await dependencyDecisionDigest(originalBody), originalBody);
+        if (original.state !== 'not_observed') {
+            await outputReceipt(original);
+            if (original.state === 'unavailable')
+                throw new CliError('dependency_decision_unavailable', 'Keep the original decision for recovery. Nothing was submitted.', 2);
+            return;
+        }
+    }
+    const value = preparation(await api(`${base}/${id}`, auth), scope);
+    if (value.id !== id)
+        throw invalid();
+    if (action === 'preparation') {
+        output('dependency_preparation', value, summary(value));
+        return;
+    }
+    if (action === 'compatibility') {
+        if (!sha(args[2]))
+            throw new CliError('arguments_invalid', 'Choose the exact candidate digest shown by the preparation.', 2);
+        const raw = await api(`${base}/${id}/compatibility?candidate_id=${args[2]}&page=${page}`, auth);
+        if (!compatibilityPageMatches(raw, id, args[2], Number(page)))
+            throw invalid();
+        const lines = raw.results.map(one => {
+            return [`${terminalText(one.name ?? 'Incomplete operation declaration')}  ${terminalText(one.state)}${one.reason ? `  ${terminalText(one.reason)}` : ''}`,
+                ...one.gaps.map(gap => '  ' + terminalText(gap)),
+                ...(one.protocol_metadata ? [
+                    `  Explicit source mapping: ${one.protocol_metadata.explicit_expectations_match === null ? 'not declared' : one.protocol_metadata.explicit_expectations_match ? 'declarations match, not behavior proof' : 'differs'}`,
+                    ...protocolProfileLines(one.protocol_metadata.source).map(line => '  Source: ' + terminalText(line)),
+                    ...protocolProfileLines(one.protocol_metadata.package).map(line => '  Package: ' + terminalText(line)),
+                ] : [])].join('\n');
+        });
+        output('dependency_compatibility', raw, (lines.join('\n') || 'No operation declarations on this page.') + `\nPage ${raw.page}, ${raw.count} declarations. Runtime behavior remains unvalidated.`);
+        return;
+    }
+    let body;
+    if (originalBody)
+        body = originalBody;
+    else if (action === 'continue-preparation') {
+        if (!interactive(options))
+            throw new CliError('request_file_required', 'Use --file with {"action":"continue","continuation_digest":"<original digest>"}. The current cursor will not be silently substituted during recovery.', 2);
+        const cursor = value.continuation_digest;
+        if (!sha(cursor))
+            throw invalid();
+        body = { action: 'continue', continuation_digest: cursor };
+    }
+    else if (action === 'cancel-preparation')
+        body = { action: 'withdraw' };
+    else {
+        if (!interactive(options))
+            throw new CliError('request_file_required', 'Read the preparation and operation declarations, then use --file with an exact decision and --approve-configuration.', 2);
+        output('dependency_preparation_review', value, summary(value) + '\n' + value.unresolved_semantics.map(terminalText).join('\n'));
+        const choices = value.candidates.filter(one => one.all_declared_operations_match).map(one => ({ value: one.candidate_id, label: `${one.name} ${one.version}`,
+            detail: `${one.counts.declaration_match ?? 0} operation declarations match. Behavioral validation remains required.` }));
+        if (value.generated_authoring_supported)
+            choices.push({ value: 'generated', label: 'Authorize bounded service authoring', detail: 'Only the declared external HTTP/MCP surface. No replacement of agent business logic.' });
+        choices.push({ value: 'cancel', label: 'Not now', detail: '' });
+        const chosen = await selectOne('Service preparation', choices, options.signal);
+        if (chosen === 'cancel')
+            return;
+        body = decisionBody({ action: chosen === 'generated' ? 'generated' : 'catalog', ...(chosen === 'generated' ? {} : { candidate_id: chosen }), acknowledge_coverage_gaps: true });
+    }
+    const digest = await dependencyDecisionDigest(body);
+    const readCommand = `firedrill connections preparation-decision ${id} ${digest} --world ${scope.world} --workspace ${scope.workspace}`;
+    output('dependency_decision_review', { preparation_id: id, decision_digest: digest, decision: body }, `Preparation: ${id}\nDecision: ${digest}\n${dependencyDecisionCanonical(body)}\nCheck original: ${readCommand}\nKeep this exact metadata in a decision file for continuation. Only this connection changes. No simulation starts.`);
+    const original = await readDecision(id, digest, body);
+    if (original.state !== 'not_observed') {
+        await outputReceipt(original);
+        if (original.state === 'unavailable')
+            throw new CliError('dependency_decision_unavailable', 'Keep the original decision for recovery. Nothing was submitted.', 2);
+        return;
+    }
+    if (!options.approve && (!interactive(options) || !await selectOne('Apply this exact reviewed decision?', [{ value: false, label: 'Not now' }, { value: true, label: 'Apply decision' }], options.signal)))
+        throw new CliError('approval_required', 'No decision was submitted. Use --approve-configuration only after reviewing this exact scope.', 2);
+    try {
+        const result = preparation(await api(`${base}/${id}`, { ...auth, method: 'POST', body }), scope);
+        if (result.id !== id || result.actor_id !== scope.owner)
+            throw invalid();
+        const accepted = await readDecision(id, digest, body);
+        if (accepted.state !== 'accepted')
+            throw invalid();
+        output('dependency_decision_receipt', accepted, receiptSummary(accepted));
+        output('dependency_preparation', result, summary(result));
+    }
+    catch (error) {
+        output('dependency_decision_recovery', { preparation_id: id, decision_digest: digest, decision: body }, `The original reply was not confirmed. Do not choose another decision. Read original: ${readCommand}\nContinue only with the exact original decision file after readback.`);
+        throw error;
+    }
+}

package/dist/cli/src/director-tool-setup.js

@@ -0,0 +1,104 @@
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { checkedToolSetupProposal, toolSetupRequestDigest } from '../../contracts/tool-setup-proposal.js';
+import { startToolGroup } from './tool-groups.js';
+import { toolGroupReads } from './tool-group-reads.js';
+const invalid = () => new CliError('tool_setup_proposal_unconfirmed', 'The original tool selection could not be confirmed for this account and world. No tools were started.', 2);
+export { toolSetupProposalId } from '../../contracts/tool-setup-proposal.js';
+export async function toolSetupProposal(context, id, signal) {
+    const key = identifier(id);
+    const raw = await api(`${context.prefix}/tool-setup-proposals/${key}`, { actor: context.owner, workspace: context.workspace, signal });
+    let value;
+    try {
+        value = checkedToolSetupProposal(raw);
+    }
+    catch {
+        throw invalid();
+    }
+    if (value.id !== key || value.actor_id !== context.owner || value.world_id !== context.world
+        || value.workspace_id !== context.workspace
+        || await toolSetupRequestDigest(value.request) !== value.request_sha256)
+        throw invalid();
+    return value;
+}
+function draft(value) {
+    return { name: value.request.name, duration_seconds: value.request.duration_seconds,
+        selections: value.request.selections.map(one => one.release_id !== null
+            ? { release_id: identifier(one.release_id), dataset_id: null }
+            : { implementation_id: identifier(one.implementation_id), dataset_id: one.dataset_id }) };
+}
+async function existing(context, value, signal, output) {
+    const reads = toolGroupReads(context, signal);
+    let row;
+    try {
+        row = await reads.original(value.id);
+    }
+    catch (error) {
+        if (error instanceof CliError && error.httpStatus === 404)
+            return false;
+        throw new CliError('tool_group_acceptance_unconfirmed', `The original setup could not be read. No replacement was submitted. Use tools setup-status ${value.id} --workspace ${context.workspace}.`, 2);
+    }
+    if (row.name !== value.request.name || row.duration_seconds !== value.request.duration_seconds
+        || row.counts.selected !== value.request.selections.length)
+        throw invalid();
+    let seen = 0, page = 1;
+    while (seen < value.request.selections.length) {
+        const members = await reads.members(row.id, page);
+        if (members.count !== value.request.selections.length || !members.results.length)
+            throw invalid();
+        for (const member of members.results) {
+            const selected = value.request.selections[seen];
+            if (!selected || member.position !== seen || (selected.release_id !== null
+                ? member.release_id !== selected.release_id || member.dataset !== null
+                : member.implementation_id !== selected.implementation_id || member.release_id !== null
+                    || (member.dataset?.id ?? null) !== selected.dataset_id))
+                throw invalid();
+            seen++;
+        }
+        if (Boolean(members.next) !== (seen < value.request.selections.length))
+            throw invalid();
+        page++;
+    }
+    output('tool_setup', row, `${terminalText(row.name)}\nSetup: ${row.id}\n`
+        + `${row.counts.selected} selected · ${row.counts.running} running. Original setup retained; no new tools were started.\n`
+        + `Use tools setup-members ${row.id} to inspect the original instances.`);
+    return true;
+}
+export async function reviewToolSetupProposal(context, id, options, output) {
+    const value = await toolSetupProposal(context, id, options.signal);
+    // This key belongs to the original recommendation in both the portal and
+    // terminal. Reopening its review never substitutes another setup intent.
+    if (await existing(context, value, options.signal, output))
+        return;
+    const selected = draft(value);
+    output('tool_setup_proposal', value, [value.request.name,
+        ...value.selection_choices.map((one, index) => `${index + 1}. ${one.name} ${one.version}`
+            + (one.dataset_id ? ` · ${one.dataset_name ?? 'Saved dataset'}` : ' · packaged data')),
+        `Runtime: ${value.request.duration_seconds} seconds.`,
+        value.current && value.can_review ? 'Review the combined runtime budget before starting tools.'
+            : 'This selection or its access changed. No tools were started.',
+        `Original setup request: ${value.id}`,
+    ].map(terminalText).join('\n'));
+    if (!value.current || !value.can_review)
+        return;
+    if (options.json || !process.stdin.isTTY || !process.stderr.isTTY) {
+        output('tool_setup_review_required', { request_key: value.id, selection: selected, requires_runtime_quotes: true,
+            requires_explicit_start_consent: true }, `Review this selection in an interactive conversation with /start-tools ${value.id}. `
+            + `For automation, obtain normal runtime quotes for these exact selections, add each usage_quote_id to a setup file and use tools start --file <file> --request-key ${value.id} --approve-tool-change --workspace ${context.workspace} --json. No tools were started.`);
+        return;
+    }
+    const review = await selectOne('Review the selected tools and runtime budget?', [
+        { value: false, label: 'Not now' }, { value: true, label: 'Review budget', detail: 'Starting still needs your explicit budget approval.' },
+    ], options.signal);
+    if (!review) {
+        output('tool_setup_kept', { proposal_id: value.id }, `Selection kept. Use /start-tools ${value.id} when ready.`);
+        return;
+    }
+    await startToolGroup(context, selected, { ...options, workspace: context.workspace, request: value.id }, output, async () => {
+        const current = await toolSetupProposal(context, value.id, options.signal);
+        if (!current.current || !current.can_review || current.request_sha256 !== value.request_sha256)
+            throw new CliError('tool_setup_proposal_changed', 'The selected inputs or access changed during review. No setup was submitted.', 2);
+    });
+}

package/dist/cli/src/driver-review.js

@@ -0,0 +1,225 @@
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { workspaceLink } from './browser-links.js';
+import { nativeMetadataCanonical } from '../../contracts/local-value-source-contracts.js';
+import { planningDriverMatches } from '../../contracts/planning-contracts.js';
+import { driverReviewMatches, driverReviewActionsMatch, driverReviewSourcesMatch } from '../../contracts/driver-review-contracts.js';
+const interactive = (options) => !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+const auth = (context, signal) => ({ actor: context.owner, workspace: context.workspace, signal });
+const problem = () => new CliError('driver_review_changed', 'The saved input recipe could not be confirmed. Read its current review before approving input.', 2);
+const display = (value, omitted = false) => omitted ? 'Omitted from this presentation'
+    : value === null ? 'Not declared' : value.length > 600 ? value.slice(0, 600) + ' [display shortened; full authorized presentation is available with --json]' : value;
+const command = (context, review, view = 'scope', baseline) => `firedrill driver review ${review.id} --world ${context.world} --workspace ${context.workspace}`
+    + (view === 'scope' ? '' : ` --view ${view}`) + (baseline ? ` --baseline ${baseline.id}` : '');
+const reviewLink = (context, review, baseline) => workspaceLink(context.workspace, `/worlds/${context.world}/plan#driver-recipe`, {
+    driver_review: review.id, driver_review_sha256: review.review_sha256, ...(baseline ? { driver_baseline: baseline.id } : {})
+});
+function locator(value) {
+    if (!value)
+        return '';
+    return `${value.kind}: ${display(value.value, value.value === null && value.presentation_omitted)}`
+        + (value.name === null ? '' : ` (${value.name})`) + (value.exact ? ' [exact]' : '')
+        + (value.frames.length ? `; frames: ${value.frames.join(' > ')}` : '')
+        + (value.presentation_omitted ? '; some presentation fields omitted' : '');
+}
+function completion(review) {
+    const value = review.completion;
+    if (!value)
+        return 'Completion details unavailable.';
+    return [`Completion: ${value.label}`, value.locator ? `Marker: ${locator(value.locator)}` : '',
+        value.result_locator ? `Result: ${locator(value.result_locator)}` : '',
+        value.page === null ? '' : `Completion page: ${value.page + 1}`,
+        value.attribute === null ? '' : `Marker attribute: ${value.attribute}`,
+        value.literal_value_omitted ? 'Literal completion values are omitted.' : ''].filter(Boolean).join('\n');
+}
+export function driverReviewText(review) {
+    return [`Prepared input: ${review.kind.replaceAll('_', ' ')} · ${review.revision}`,
+        `${review.current ? 'Current' : 'Historical'} recipe${review.available ? '' : ' · details unavailable'}`,
+        ...review.scope.map(one => `${one.label}: ${display(one.value, one.omitted)}`), completion(review),
+        `${review.action_count} declared actions · ${review.source_count} source references`,
+        review.omitted_count ? 'Some literal or private fields are omitted. A hidden difference is not proof that the complete recipe is unchanged.' : '',
+        'Reading this recipe does not approve input or execution.'].filter(Boolean).join('\n');
+}
+function scopeChanges(review, baseline) {
+    const before = new Map(baseline.scope.map(one => [one.name, one]));
+    const after = new Map(review.scope.map(one => [one.name, one]));
+    const lines = [];
+    for (const name of new Set([...before.keys(), ...after.keys()])) {
+        const old = before.get(name), current = after.get(name);
+        if (nativeMetadataCanonical(old ?? null) === nativeMetadataCanonical(current ?? null))
+            continue;
+        lines.push(`${current?.label ?? old.label}: ${old ? display(old.value, old.omitted) : 'Not declared'} -> ${current ? display(current.value, current.omitted) : 'Not declared'}`);
+    }
+    if (nativeMetadataCanonical(baseline.completion) !== nativeMetadataCanonical(review.completion))
+        lines.push(`Completion changed.\nBefore: ${completion(baseline)}\nAfter: ${completion(review)}`);
+    if (baseline.kind !== review.kind)
+        lines.push(`Driver: ${baseline.kind} -> ${review.kind}`);
+    return ['Scope and completion changes', ...(lines.length ? lines : ['No change in the visible scope or completion fields.']),
+        'Comparison covers retained declarations, not observed behavior or an applied source change. Omitted values may differ.'].join('\n');
+}
+async function savedReview(context, id, signal) {
+    const reviewId = identifier(id);
+    const value = await api(`${context.prefix}/driver-reviews/${reviewId}`, auth(context, signal));
+    if (!driverReviewMatches(value, context.world, { id: reviewId }))
+        throw problem();
+    return value;
+}
+export async function currentDriverReview(context, driver, configurationRevision, signal) {
+    const value = await api(`${context.prefix}/driver-review?contract_sha256=${encodeURIComponent(driver.contract_sha256)}`, auth(context, signal));
+    if (!driverReviewMatches(value, context.world, { contract: driver.contract_sha256 }) || !value.current || !value.available
+        || value.kind !== driver.kind || value.revision !== driver.revision || value.configuration.revision !== configurationRevision
+        || nativeMetadataCanonical(value.basis) !== nativeMetadataCanonical(driver.basis))
+        throw problem();
+    return value;
+}
+async function selectedBaseline(context, review, id, signal) {
+    if (!id)
+        return null;
+    const baseline = await savedReview(context, id, signal);
+    if (!baseline.available || baseline.id === review.id)
+        throw new CliError('driver_review_baseline_invalid', 'Choose a different earlier retained recipe from the same world.', 2);
+    return baseline;
+}
+async function entries(context, review, kind, options, signal) {
+    if (!review.available)
+        throw new CliError('driver_review_unavailable', 'The original input recipe details are no longer available.', 2);
+    const query = new URLSearchParams({ review_sha256: review.review_sha256, page: String(options.page), page_size: String(options.pageSize),
+        q: options.search, change: options.change });
+    if (options.baseline)
+        query.set('baseline', options.baseline.id);
+    const value = await api(`${context.prefix}/driver-reviews/${review.id}/${kind}?${query}`, auth(context, signal));
+    const selection = { baseline: options.baseline?.id ?? null, query: options.search, change: options.change, page: options.page };
+    if (!(kind === 'actions' ? driverReviewActionsMatch(value, context.world, review, selection)
+        : driverReviewSourcesMatch(value, context.world, review, selection)))
+        throw problem();
+    const page = value;
+    if (page.page_size !== options.pageSize || page.baseline_review_sha256 !== (options.baseline?.review_sha256 ?? null))
+        throw problem();
+    return page;
+}
+function actionText(value) {
+    return [`${value.position}. ${value.id}: ${value.action} (${value.effect}, page ${value.page + 1}, ${value.timeout_ms}ms)`,
+        value.locator ? locator(value.locator) : '', value.path === null ? '' : `Path: ${value.path}`,
+        value.input_path === null ? '' : `Input field: ${value.input_path}`, value.output === null ? '' : `Output field: ${value.output}`,
+        value.point === null ? '' : `Point: ${value.point.join(', ')}`,
+        value.has_literal_value ? 'Literal input value omitted.' : '', value.presentation_omitted ? 'Some presentation fields omitted.' : ''].filter(Boolean).join('\n');
+}
+function sourceText(value) {
+    return `${value.root ?? '[root omitted]'}/${value.path ?? '[path omitted]'}${value.line === null ? '' : ':' + value.line}`
+        + ` · ${value.sha256.slice(0, 12)}` + (value.presentation_omitted ? ' · details omitted' : '');
+}
+function pageText(kind, page) {
+    const rows = page.results.map(row => {
+        const render = (value) => 'action' in value ? actionText(value) : sourceText(value);
+        return [`${row.key} · ${row.change}`, row.before ? 'Before\n' + render(row.before) : '',
+            row.after ? (row.before ? 'After\n' : '') + render(row.after) : '',
+            row.omitted_change ? 'The retained definition changed in omitted fields.' : '',
+            'order_changed' in row && row.order_changed ? 'Action order changed.' : ''].filter(Boolean).join('\n');
+    });
+    return [`${kind === 'actions' ? 'Declared actions' : 'Source references'} · page ${page.page} · ${page.count} matching entries`,
+        ...(rows.length ? rows : ['No entries match this page and filter.'])].join('\n\n');
+}
+async function browse(context, review, kind, baseline, options, output) {
+    let page = 1;
+    while (true) {
+        const result = await entries(context, review, kind, { page, pageSize: 20, search: '', change: 'all', baseline }, options.signal);
+        output('driver_review_' + kind, { review_id: review.id, review_sha256: review.review_sha256, page: result }, pageText(kind, result));
+        const choices = [{ value: 'back', label: 'Back to input review' }];
+        if (result.next)
+            choices.push({ value: 'next', label: 'Next page' });
+        if (page > 1)
+            choices.push({ value: 'previous', label: 'Previous page' });
+        const choice = await selectOne('Recipe details', choices, options.signal);
+        if (choice === 'back')
+            return;
+        page += choice === 'next' ? 1 : -1;
+    }
+}
+export async function reviewDriverInput(context, setup, options, output) {
+    const driver = setup.execution_driver;
+    if (!driver?.requires_input)
+        return;
+    const inspectCommand = `firedrill driver review --world ${context.world} --workspace ${context.workspace} --contract-sha256 ${driver.contract_sha256}`;
+    let review;
+    try {
+        review = await currentDriverReview(context, driver, setup.configuration_revision, options.signal);
+    }
+    catch (error) {
+        if (error instanceof CliError && ['driver_review_unavailable', 'driver_review_changed'].includes(error.code))
+            output('driver_review_required', { world_id: context.world, contract_sha256: driver.contract_sha256, command: inspectCommand }, `The current readable input recipe is unavailable or changed.\n${inspectCommand}`);
+        throw error;
+    }
+    output('driver_review', { review, command: inspectCommand, actions_command: command(context, review, 'actions'),
+        sources_command: command(context, review, 'sources'), web_url: reviewLink(context, review) }, driverReviewText(review) + '\n\n' + command(context, review, 'actions') + '\n' + command(context, review, 'sources'));
+    if (!interactive(options) || options.approveAgentInput)
+        return;
+    while (true) {
+        const choices = [{ value: 'continue', label: 'Continue to input approval' },
+            { value: 'actions', label: 'Inspect declared actions' }, { value: 'sources', label: 'Inspect source references' }];
+        if (review.previous?.available)
+            choices.push({ value: 'before', label: 'Compare with the previous retained recipe' });
+        choices.push({ value: 'cancel', label: 'Cancel' });
+        const choice = await selectOne('Prepared input recipe', choices, options.signal);
+        if (choice === 'continue')
+            return;
+        if (choice === 'cancel')
+            throw new CliError('canceled', 'No input approval or new plan was saved.', 130);
+        if (choice === 'before') {
+            const baseline = await selectedBaseline(context, review, review.previous.id, options.signal);
+            if (!baseline)
+                throw problem();
+            output('driver_review_comparison', { review, baseline }, 'Before\n' + driverReviewText(baseline) + '\n\nAfter\n' + driverReviewText(review) + '\n\n' + scopeChanges(review, baseline));
+            const detail = await selectOne('Recipe changes', [{ value: 'back', label: 'Back to current recipe' },
+                { value: 'actions', label: 'Inspect action changes' }, { value: 'sources', label: 'Inspect source changes' }], options.signal);
+            if (detail !== 'back')
+                await browse(context, review, detail, baseline, options, output);
+        }
+        else
+            await browse(context, review, choice, null, options, output);
+    }
+}
+function integer(value, fallback, maximum) {
+    if (value === undefined)
+        return fallback;
+    if (!/^[1-9][0-9]*$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) > maximum)
+        throw new CliError('arguments_invalid', `Choose a page value from 1 to ${maximum}.`, 2);
+    return Number(value);
+}
+export async function driverReviewCommand(args, options, output) {
+    if (args[0] !== 'review' || args.length > 2 || args[1] && options.contract)
+        throw new CliError('arguments_invalid', 'Use driver review [review-id]. Use --contract-sha256 only for the current recipe.', 2);
+    const view = options.view ?? 'scope', change = options.change ?? 'all', search = (options.search ?? '').trim();
+    if (!['scope', 'actions', 'sources'].includes(view) || !['all', 'added', 'removed', 'changed', 'unchanged'].includes(change)
+        || search.length > 200 || /[\x00-\x1f\x7f]/.test(search)
+        || change !== 'all' && !options.baseline
+        || view === 'scope' && (options.page !== undefined || options.pageSize !== undefined || options.search !== undefined || options.change !== undefined))
+        throw new CliError('arguments_invalid', 'Choose --view scope, actions or sources. Page/search filters apply only to actions or sources; change filters also need an explicit --baseline.', 2);
+    const context = await selectedWorld({ workspace: options.workspace, world: options.world, interactive: interactive(options),
+        openBrowser: options.openBrowser, signal: options.signal });
+    let review;
+    if (args[1])
+        review = await savedReview(context, args[1], options.signal);
+    else {
+        if (options.contract && !/^[a-f0-9]{64}$/.test(options.contract))
+            throw new CliError('arguments_invalid', 'Use the exact canonical driver digest from current planning.', 2);
+        const setup = await api(`${context.prefix}/simulation-plan`, auth(context, options.signal));
+        if (!planningDriverMatches(setup) || !setup.execution_driver || options.contract && setup.execution_driver.contract_sha256 !== options.contract)
+            throw problem();
+        review = await currentDriverReview(context, setup.execution_driver, setup.configuration_revision, options.signal);
+    }
+    const baseline = await selectedBaseline(context, review, options.baseline, options.signal);
+    const data = { world_id: context.world, review, baseline, web_url: reviewLink(context, review, baseline),
+        actions_command: command(context, review, 'actions', baseline), sources_command: command(context, review, 'sources', baseline) };
+    const readable = (baseline ? 'Before\n' + driverReviewText(baseline) + '\n\nAfter\n' : '') + driverReviewText(review)
+        + (baseline ? '\n\n' + scopeChanges(review, baseline) : '');
+    if (view === 'scope') {
+        output('driver_review', data, readable + '\n\n' + data.actions_command + '\n' + data.sources_command);
+        return;
+    }
+    const result = await entries(context, review, view, { page: integer(options.page, 1, 10000),
+        pageSize: integer(options.pageSize, 20, 100), search, change, baseline }, options.signal);
+    output('driver_review_' + view, { ...data, page: result }, readable + '\n\n' + pageText(view, result));
+}