firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/agent-changes.js

@@ -0,0 +1,496 @@
+import { workspaceLink } from './browser-links.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, unlink } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { api } from './auth.js';
+import { privateDirectory } from './credentials.js';
+import { CliError } from './http.js';
+import { selectMany, selectOne } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { selectedWorkspace } from './world-access.js';
+import { candidateCopy, forgetCandidateCopy } from './candidate-copy.js';
+import { sourceChangeMatches, sourceChangePageMatches, sourceChangeProposalMatches, sourceChangeCommandMatches, sourceChangeDiffMatches, agentComparisonMatches, agentComparisonRequestMatches, patchSourceFileMatches, sourceMetadataDigest } from '../../contracts/agent-change-contracts.js';
+const CAPACITY = 65536;
+const HASH = /^[a-f0-9]{64}$/;
+const MUTATIONS = ['propose', 'approve', 'resume-draft', 'accept', 'retry-save', 'dismiss', 'compare'];
+const serverAction = (action) => action === 'resume-draft' ? 'resume' : action === 'retry-save' ? 'retry' : action;
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const digest = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const tty = (options) => !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+const prefix = (scope, campaign) => `/api/workspaces/${identifier(scope.workspace)}/campaigns/${identifier(campaign)}`;
+const auth = (scope, options) => ({ actor: scope.owner, workspace: scope.workspace, signal: options.signal });
+const link = (row) => workspaceLink(row.workspace_id, `/campaigns/${identifier(row.baseline_id)}`);
+const invalidReceipt = () => new CliError('agent_change_receipt_invalid', 'The saved response did not match this workspace, baseline or original source-change request. Inspect the original request before continuing. No replacement request was submitted.');
+function selectedPath(path, scope) {
+    const found = path.match(/^\/api\/workspaces\/([^/]+)\/campaigns\/([^/]+)(?:\/source-changes\/([^/?]+))?/);
+    if (!found || found[1] !== scope.workspace)
+        throw invalidReceipt();
+    return { campaign: identifier(found[2]), change: found[3] ? identifier(found[3]) : undefined };
+}
+async function changePage(path, scope, options, page) {
+    const selected = selectedPath(path, scope);
+    const result = await api(`${path}?page=${page}`, auth(scope, options));
+    if (!sourceChangePageMatches(result, scope.workspace, selected.campaign, page)
+        || !result.results.every(row => sourceChangeMatches(row, scope.workspace, selected.campaign)))
+        throw invalidReceipt();
+    return result;
+}
+async function filePage(path, scope, options, page) {
+    const selected = selectedPath(path, scope), search = options.search ?? '';
+    const result = await api(`${path}?page=${page}&q=${encodeURIComponent(search)}`, auth(scope, options));
+    if (!sourceChangePageMatches(result, scope.workspace, selected.campaign, page) || result.query !== search.trim()
+        || !result.results.every(patchSourceFileMatches))
+        throw invalidReceipt();
+    return result;
+}
+async function comparisonsPage(path, scope, options, page) {
+    const selected = selectedPath(path, scope);
+    if (!selected.change)
+        throw invalidReceipt();
+    const result = await api(`${path}/comparisons?page=${page}${options.request ? '&request_key=' + identifier(options.request) : ''}`, auth(scope, options));
+    if (!sourceChangePageMatches(result, scope.workspace, selected.campaign, page) || result.change_id !== selected.change
+        || !result.results.every(row => agentComparisonMatches(row, scope.workspace, selected.campaign, selected.change)))
+        throw invalidReceipt();
+    if (options.request && !agentComparisonRequestMatches(result, scope.workspace, selected.campaign, selected.change, scope.owner, identifier(options.request)))
+        throw invalidReceipt();
+    return result;
+}
+function description(row) {
+    return [`${row.title} · ${row.state.replaceAll('_', ' ')}`, row.id, row.instruction,
+        ...row.files.map(file => `${file.path} · ${file.size} bytes · ${file.sha256}`),
+        `Source scope: ${row.scope_sha256}`, ...(row.draft_sha256 ? [`Draft: ${row.draft_sha256}`] : []),
+        ...(!row.current ? ['The source, approval or evidence is no longer current. New privileged work is not authorized.'] : []),
+        ...(row.problem ? [row.problem] : []), ...(row.candidate_world_id ? [`Candidate: ${workspaceLink(row.workspace_id, `/worlds/${identifier(row.candidate_world_id)}`)}`] : []),
+        ...(row.command_receipt?.recovered ? ['Original command receipt recovered. No replacement operation was queued.'] : []), link(row)].join('\n');
+}
+function comparisonDescription(row) {
+    return [`${row.id} · ${row.state.replaceAll('_', ' ')}`, `${row.retained_count} original scenarios · ${row.additional_count} additional · ${row.criterion_count} frozen criteria`,
+        `${row.repetitions} repetitions · Parallelism ${row.parallelism} · ${row.trial_seconds} seconds per drill`,
+        ...(row.current === false ? ['This saved setup is unavailable for new work.']
+            : row.current === null ? ['Current inputs and access are reviewed when configuring each comparison world.'] : []), ...(row.problem ? [row.problem] : []),
+        ...(row.control_world_id ? [`Control: ${workspaceLink(row.workspace_id, `/worlds/${identifier(row.control_world_id)}`)}`] : []),
+        ...(row.candidate_world_id ? [`Candidate: ${workspaceLink(row.workspace_id, `/worlds/${identifier(row.candidate_world_id)}`)}`] : [])].join('\n');
+}
+async function readObject(path, privateFile = false) {
+    const absolute = resolve(path), before = await lstat(absolute);
+    if (!before.isFile() || before.isSymbolicLink() || before.size < 2 || before.size > CAPACITY
+        || privateFile && (process.getuid && before.uid !== process.getuid() || process.platform !== 'win32' && !!(before.mode & 0o077))) {
+        throw new CliError('agent_change_file_invalid', 'Use a bounded regular JSON file. Recovery files must remain private to this OS user.', 2);
+    }
+    const file = await open(absolute, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const actual = await file.stat();
+        if (actual.dev !== before.dev || actual.ino !== before.ino || actual.size !== before.size || actual.mtimeMs !== before.mtimeMs
+            || !actual.isFile() || privateFile && (process.getuid && actual.uid !== process.getuid() || process.platform !== 'win32' && !!(actual.mode & 0o077)))
+            throw new Error();
+        const buffer = Buffer.alloc(actual.size);
+        let at = 0;
+        while (at < buffer.length) {
+            const part = await file.read(buffer, at, buffer.length - at, at);
+            if (!part.bytesRead)
+                throw new Error();
+            at += part.bytesRead;
+        }
+        const after = await file.stat();
+        if (after.size !== actual.size || after.mtimeMs !== actual.mtimeMs || after.ctimeMs !== actual.ctimeMs)
+            throw new Error();
+        const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(buffer));
+        if (!object(value))
+            throw new Error();
+        return value;
+    }
+    catch {
+        throw new CliError('agent_change_file_invalid', 'The exact JSON could not be read. No source-change command was submitted.', 2);
+    }
+    finally {
+        await file.close();
+    }
+}
+async function journalPath(scope, key) {
+    return join(await privateDirectory(), `agent-change-${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(key)}.json`);
+}
+function validBody(value, change, comparison = false) {
+    if (comparison)
+        return change !== null && Object.keys(value).sort().join(',') === 'additional_scenarios,draft_sha256,prepare_comparison,scope_sha256'
+            && value.prepare_comparison === true && typeof value.scope_sha256 === 'string' && HASH.test(value.scope_sha256)
+            && typeof value.draft_sha256 === 'string' && HASH.test(value.draft_sha256) && Array.isArray(value.additional_scenarios)
+            && value.additional_scenarios.every(one => typeof one === 'string' && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(one))
+            && new Set(value.additional_scenarios).size === value.additional_scenarios.length;
+    if (change === null)
+        return Object.keys(value).sort().join(',') === 'instruction,paths,title'
+            && typeof value.title === 'string' && value.title.trim().length > 0 && value.title.length <= 160
+            && typeof value.instruction === 'string' && value.instruction.trim().length > 0 && value.instruction.length <= 8000
+            && Array.isArray(value.paths) && value.paths.length > 0 && value.paths.every(path => typeof path === 'string' && path.length > 0 && path.length <= 2048)
+            && new Set(value.paths).size === value.paths.length;
+    const action = value.action;
+    return typeof action === 'string' && ['approve', 'resume', 'accept', 'retry', 'dismiss'].includes(action)
+        && typeof value.scope_sha256 === 'string' && HASH.test(value.scope_sha256)
+        && (action === 'accept' ? Object.keys(value).sort().join(',') === 'action,draft_sha256,reviewed,scope_sha256'
+            && value.reviewed === true && typeof value.draft_sha256 === 'string' && HASH.test(value.draft_sha256)
+            : Object.keys(value).sort().join(',') === 'action,scope_sha256');
+}
+async function retained(scope, key) {
+    const row = await readObject(await journalPath(scope, key), true);
+    if (row.schema !== 'firedrill.native-agent-change.v1' || row.owner !== scope.owner || row.workspace !== scope.workspace || row.key !== identifier(key)
+        || typeof row.campaign !== 'string' || identifier(row.campaign) !== row.campaign
+        || row.change !== null && (typeof row.change !== 'string' || identifier(row.change) !== row.change)
+        || row.comparison !== undefined && row.comparison !== true
+        || !object(row.body) || !validBody(row.body, row.change, row.comparison === true) || row.digest !== digest(row.body)) {
+        throw new CliError('agent_change_request_invalid', 'The retained source-change request cannot be confirmed. Nothing was submitted.');
+    }
+    return row;
+}
+async function submit(row, scope, options, output) {
+    output('agent_change_request', { request_key: row.key, campaign_id: row.campaign, change_id: row.change, body_sha256: row.digest }, `Request: ${row.key}\nIf interrupted: firedrill changes recover --workspace ${scope.workspace} --request-key ${row.key}`);
+    if (row.comparison) {
+        const body = row.body;
+        const existing = await comparisonsPage(`${prefix(scope, row.campaign)}/source-changes/${row.change}`, scope, { ...options, request: row.key }, 1);
+        if (existing.results[0]) {
+            if (existing.results[0].request_digest !== await sourceMetadataDigest({ actor_id: scope.owner, body }))
+                throw invalidReceipt();
+            output('result', existing.results[0], comparisonDescription(existing.results[0]) + '\nOriginal setup recovered. No new work was submitted.');
+            return;
+        }
+        const result = await api(`${prefix(scope, row.campaign)}/source-changes/${row.change}/comparisons`, { ...auth(scope, options), method: 'POST', idempotencyKey: row.key, body });
+        if (!row.change || !agentComparisonMatches(result, scope.workspace, row.campaign, row.change) || result.request_key !== row.key
+            || result.actor_id !== scope.owner || result.request_digest !== await sourceMetadataDigest({ actor_id: scope.owner, body }))
+            throw invalidReceipt();
+        output('result', result, comparisonDescription(result) + '\nSeparate comparison setup saved. No agent was run and no Vault access was inherited.');
+        return;
+    }
+    const result = await api(`${prefix(scope, row.campaign)}/source-changes${row.change ? '/' + row.change : ''}`, { ...auth(scope, options), method: 'POST', idempotencyKey: row.key, body: row.body });
+    if (row.change ? !sourceChangeCommandMatches(result, scope.workspace, row.campaign, row.change, scope.owner, row.key, row.body, await sourceMetadataDigest(row.body))
+        : !sourceChangeProposalMatches(result, scope.workspace, row.campaign, scope.owner, row.key, row.body))
+        throw invalidReceipt();
+    const retainedResult = await api(`${prefix(scope, row.campaign)}/source-changes/${identifier(result.id)}`, auth(scope, options));
+    if (!sourceChangeMatches(retainedResult, scope.workspace, row.campaign, result.id) || retainedResult.scope_sha256 !== result.scope_sha256
+        || retainedResult.request_key !== result.request_key || retainedResult.source_id !== result.source_id)
+        throw invalidReceipt();
+    output('result', result, description(result) + '\nOriginal source, baseline and local files are unchanged. No simulation was started.');
+}
+async function remember(scope, campaign, change, body, options, output, comparison = false) {
+    if (!validBody(body, change, comparison))
+        throw new CliError('agent_change_input_invalid', 'Review the exact source-change fields. Nothing was submitted.', 2);
+    const key = options.request ? identifier(options.request) : randomUUID();
+    const row = { schema: 'firedrill.native-agent-change.v1', ...scope, campaign, change, key, body, digest: digest(body), ...(comparison ? { comparison: true } : {}) };
+    const encoded = JSON.stringify(row);
+    if (Buffer.byteLength(encoded) > CAPACITY)
+        throw new CliError('agent_change_input_capacity', 'Use a more focused source-change request.', 2);
+    try {
+        const file = await open(await journalPath(scope, key), 'wx', 0o600);
+        try {
+            await file.writeFile(encoded);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'EEXIST')
+            throw error;
+        const prior = await retained(scope, key);
+        if (prior.campaign !== campaign || prior.change !== change || prior.digest !== row.digest || prior.comparison !== row.comparison) {
+            throw new CliError('agent_change_request_conflict', 'This request key belongs to other inputs. Recover its original request instead.', 2);
+        }
+    }
+    await submit(row, scope, options, output);
+}
+async function approval(label, options) {
+    if (options.approve || tty(options) && await selectOne(label + ' Keep the exact private local recovery request.', [{ value: false, label: 'Cancel' }, { value: true, label: 'Confirm' }], options.signal))
+        return;
+    throw new CliError('agent_change_consent_required', 'Nothing was submitted. Use --approve-change only after reviewing the exact source scope and local request retention.', 2);
+}
+async function line(label, maximum, signal) {
+    const prompt = createInterface({ input: process.stdin, output: process.stderr, terminal: false });
+    try {
+        const value = (await prompt.question(`${label}: `, { signal })).trim();
+        if (!value || value.length > maximum || /[\u0000-\u001f\u007f]/u.test(value))
+            throw new CliError('agent_change_input_invalid', 'Use nonempty text within the field capacity. Do not include credentials.', 2);
+        return value;
+    }
+    finally {
+        prompt.close();
+    }
+}
+async function choosePage(title, path, scope, options, describe, read) {
+    let page = Number(options.page ?? '1');
+    while (true) {
+        const data = read ? await read(page) : await api(`${path}${path.includes('?') ? '&' : '?'}page=${page}`, auth(scope, options));
+        const choices = data.results.map(item => ({ value: { kind: 'item', item }, ...describe(item) }));
+        if (page > 1)
+            choices.unshift({ value: { kind: 'previous' }, label: 'Previous page' });
+        if (data.next)
+            choices.push({ value: { kind: 'next' }, label: 'Next page' });
+        if (!choices.length || !data.count)
+            throw new CliError('agent_change_selection_empty', 'No matching saved items are available.');
+        const choice = await selectOne(title, choices, options.signal);
+        if (choice.kind === 'item')
+            return choice.item;
+        page += choice.kind === 'next' ? 1 : -1;
+    }
+}
+async function selectedFiles(path, scope, options) {
+    const selected = new Set();
+    let page = 1;
+    while (true) {
+        const data = await filePage(path, scope, options, page);
+        if (!data.count)
+            throw new CliError('agent_change_files_empty', 'No eligible source files match this search.');
+        const files = await selectMany('Source files Firedrill may read and propose changes to', data.results.map(file => ({ value: file.path, label: file.path, detail: `${file.size} bytes · ${file.sha256}` })), options.signal, [...selected]);
+        for (const file of data.results)
+            selected.delete(file.path);
+        for (const file of files)
+            selected.add(file);
+        const next = await selectOne(`${selected.size} files selected across pages`, [
+            ...(selected.size ? [{ value: 'done', label: 'Continue with selected files' }] : []),
+            ...(data.next ? [{ value: 'next', label: 'Next page' }] : []), ...(page > 1 ? [{ value: 'previous', label: 'Previous page' }] : []),
+            { value: 'cancel', label: 'Cancel' }
+        ], options.signal);
+        if (next === 'done')
+            return [...selected].sort();
+        if (next === 'cancel')
+            throw new CliError('canceled', 'No source-change request was submitted.', 130);
+        page += next === 'next' ? 1 : -1;
+    }
+}
+async function additionalScenarios(path, scope, options) {
+    if (options.additionalScenarios)
+        return [...new Set(options.additionalScenarios.map(identifier))].sort();
+    if (!tty(options) || !await selectOne('Include additional saved scenarios outside the original run?', [{ value: false, label: 'Use original scenarios only' }, { value: true, label: 'Choose additional scenarios' }], options.signal))
+        return [];
+    const selected = new Set();
+    let page = 1;
+    while (true) {
+        const selectedScope = selectedPath(path, scope);
+        const result = await api(`${path}/comparison-scenarios?page=${page}&q=${encodeURIComponent(options.search ?? '')}`, auth(scope, options));
+        if (!sourceChangePageMatches(result, scope.workspace, selectedScope.campaign, page) || result.change_id !== selectedScope.change
+            || result.query !== (options.search ?? '').trim() || !result.results.every(row => row && identifier(row.id) === row.id && typeof row.name === 'string' && HASH.test(row.sha256)))
+            throw invalidReceipt();
+        if (!result.count)
+            throw new CliError('comparison_scenarios_empty', 'No additional scenarios match. Run the command again without adding scenarios. Nothing was submitted.', 2);
+        const checked = await selectMany('Additional scenarios (not a guarantee they were unseen by the agent or its authors)', result.results.map(row => ({ value: identifier(row.id), label: row.name, detail: row.sha256 })), options.signal, [...selected]);
+        for (const row of result.results)
+            selected.delete(row.id);
+        for (const id of checked)
+            selected.add(id);
+        const action = await selectOne(`${selected.size} additional scenarios selected across pages`, [
+            { value: 'done', label: 'Continue' }, ...(result.next ? [{ value: 'next', label: 'Next page' }] : []),
+            ...(page > 1 ? [{ value: 'previous', label: 'Previous page' }] : []), { value: 'cancel', label: 'Cancel' }
+        ], options.signal);
+        if (action === 'done')
+            return [...selected].sort();
+        if (action === 'cancel')
+            throw new CliError('canceled', 'No comparison setup was submitted.', 130);
+        page += action === 'next' ? 1 : -1;
+    }
+}
+async function comparisonHistory(path, scope, options, output, runScope) {
+    if (!runScope) {
+        const result = await comparisonsPage(path, scope, options, Number(options.page ?? 1));
+        output('result', result, result.results.map(comparisonDescription).join('\n\n') || 'No comparison setup has been saved.');
+        if (options.request) {
+            if (!result.count)
+                output('comparison_not_received', { request_key: options.request }, 'The original setup is not confirmed. Recover the same retained request to retry; do not create a replacement request.');
+            return;
+        }
+        if (result.next)
+            output('next_page', { page: result.page + 1 }, `Next page: --page ${result.page + 1}`);
+        if (!tty(options) || !result.count)
+            return;
+        runScope = identifier((await choosePage('Saved comparison', path + '/comparisons', scope, options, row => ({ label: `${row.retained_count} original and ${row.additional_count} additional scenarios`, detail: row.state }), page => comparisonsPage(path, scope, options, page))).id);
+    }
+    const side = options.side ?? (tty(options) ? await selectOne('Simulation history', [{ value: 'control', label: 'Control' }, { value: 'candidate', label: 'Candidate' }], options.signal) : undefined);
+    if (!side || !['control', 'candidate'].includes(side))
+        throw new CliError('comparison_side_required', 'Choose --side control or --side candidate for comparison run history.', 2);
+    const selectedScope = selectedPath(path, scope);
+    const result = await api(`${path}/comparisons/${identifier(runScope)}/runs?side=${side}&page=${options.page ?? '1'}`, auth(scope, options));
+    if (!sourceChangePageMatches(result, scope.workspace, selectedScope.campaign, Number(options.page ?? 1)) || result.change_id !== selectedScope.change
+        || result.comparison_id !== runScope || result.side !== side || !result.results.every(row => row && identifier(row.id) === row.id
+        && row.report_url === `/campaigns/${row.id}` && Number.isSafeInteger(row.planned_trials) && row.planned_trials > 0))
+        throw invalidReceipt();
+    output('result', result, result.results.map(row => `${row.id} · ${row.state} · ${row.planned_trials} planned drills\n${workspaceLink(scope.workspace, `/campaigns/${identifier(row.id)}`)}`).join('\n\n') || 'No simulations have been saved for this side yet.');
+    if (result.next)
+        output('next_page', { page: result.page + 1 }, `Next page: --page ${result.page + 1}`);
+}
+async function showDiffs(row, path, scope, options, output, position) {
+    const files = row.draft_files;
+    if (!row.current || !row.draft_sha256 || !files?.length)
+        throw new CliError('agent_change_draft_unavailable', 'No current draft is available to inspect.');
+    if (position !== undefined && (!/^[1-9][0-9]*$/.test(position) || Number(position) > files.length))
+        throw new CliError('arguments_invalid', 'Choose a one-based file position from this draft.', 2);
+    for (let index = 0; index < files.length; index++) {
+        if (position !== undefined && index !== Number(position) - 1)
+            continue;
+        const file = files[index];
+        const data = await api(`${path}/files/${index}`, auth(scope, options));
+        if (!sourceChangeDiffMatches(data, row, file, index)) {
+            throw new CliError('agent_change_draft_changed', 'The diff does not match the selected draft. Review it again before accepting.');
+        }
+        output('agent_change_diff', { ...data, draft_sha256: row.draft_sha256, position: index + 1 }, data.diff);
+    }
+}
+export async function changesCommand(args, options, output) {
+    if (options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page) || (options.search?.length ?? 0) > 200)
+        throw new CliError('arguments_invalid', 'Choose valid paging and search options.', 2);
+    if (args.length > 4)
+        throw new CliError('arguments_invalid', 'Use changes [campaign] [action] [change] [file-position].', 2);
+    const interactive = tty(options), scope = await selectedWorkspace({ ...options, interactive });
+    if (args[0] === 'copy-resume' || args[0] === 'copy-forget') {
+        if (args.length !== 1 || !options.request || options.page || options.search || options.file || options.reviewedDraft
+            || options.into || options.approve || options.additionalScenarios || options.side)
+            throw new CliError('arguments_invalid', 'Use changes copy-resume --request-key <id> --workspace <id>.', 2);
+        return args[0] === 'copy-forget' ? forgetCandidateCopy(scope, options, output) : candidateCopy(scope, undefined, undefined, options, output);
+    }
+    if (args[0] === 'recover' || args[0] === 'forget') {
+        if (args.length !== 1 || !options.request || options.page || options.search || options.file || options.reviewedDraft
+            || options.into || options.approveDownload || options.additionalScenarios || options.side)
+            throw new CliError('arguments_invalid', 'Use changes recover|forget --request-key <id> --workspace <id>.', 2);
+        const row = await retained(scope, options.request);
+        if (args[0] === 'recover')
+            return submit(row, scope, options, output);
+        await approval('Remove only this local recovery copy? It will not cancel an approved draft or candidate save.', options);
+        await unlink(await journalPath(scope, row.key));
+        output('result', { request_key: row.key, local_copy_removed: true }, 'Local recovery copy removed. Accepted server work is unchanged.');
+        return;
+    }
+    let campaign = args[0] ? identifier(args[0]) : undefined;
+    if (!campaign && !interactive)
+        throw new CliError('campaign_required', 'Pass a saved campaign ID, or run firedrill changes interactively.', 2);
+    if (!campaign) {
+        const row = await choosePage('Baseline simulation', `/api/workspaces/${scope.workspace}/simulations?q=${encodeURIComponent(options.search ?? '')}`, scope, options, row => ({ label: row.name, detail: row.status }));
+        campaign = identifier(row.campaign_id);
+    }
+    const base = prefix(scope, campaign), path = `${base}/source-changes`;
+    let action = args[1];
+    const guided = interactive && !action;
+    if (guided)
+        action = await selectOne('Agent source changes', [{ value: 'list', label: 'Review saved changes' },
+            { value: 'propose', label: 'Propose a scoped change' }], options.signal);
+    action ??= 'list';
+    if (!['list', 'files', 'show', 'diff', 'copy', 'comparisons', 'comparison-runs', ...MUTATIONS].includes(action)
+        || !MUTATIONS.includes(action) && (options.file || !['copy', 'comparisons'].includes(action) && options.request || options.approve || options.reviewedDraft)
+        || action !== 'propose' && options.file || action !== 'accept' && options.reviewedDraft
+        || action !== 'copy' && !guided && (options.into || options.approveDownload)
+        || args[3] && !['diff', 'comparison-runs'].includes(action) || ['files', 'list', 'propose'].includes(action) && args[2]
+        || options.search && !['files', 'propose', 'compare'].includes(action) && !!args[0]
+        || options.additionalScenarios && action !== 'compare' || options.side && !['comparisons', 'comparison-runs'].includes(action)
+        || options.page && !['files', 'list', 'comparisons', 'comparison-runs'].includes(action) && !!args[0])
+        throw new CliError('arguments_invalid', 'Use only the options for the selected source-change action.', 2);
+    if (action === 'files' || action === 'list' && !guided) {
+        const data = action === 'files' ? await filePage(base + '/source-change-files', scope, options, Number(options.page ?? 1))
+            : await changePage(path, scope, options, Number(options.page ?? 1));
+        output('result', data, [data.results.map(row => 'path' in row ? `${row.path} · ${row.size} bytes · ${row.sha256}` : description(row)).join('\n\n') || 'No matching items.',
+            ...(data.next ? [`Next page: --page ${data.page + 1}`] : [])].join('\n'));
+        return;
+    }
+    if (action === 'propose') {
+        let body;
+        if (options.file)
+            body = await readObject(options.file);
+        else {
+            if (!interactive)
+                throw new CliError('agent_change_file_required', 'Pass --file <change.json> with title, instruction and paths, or run firedrill changes interactively.', 2);
+            const paths = await selectedFiles(base + '/source-change-files', scope, options);
+            const title = await line('Change name (up to 160 characters)', 160, options.signal);
+            const instruction = await line('Intended behavior (up to 8,000 characters, no credentials)', 8000, options.signal);
+            body = { title, instruction, paths };
+        }
+        if (!validBody(body, null))
+            throw new CliError('agent_change_input_invalid', 'Use title, instruction and unique paths only.', 2);
+        output('agent_change_scope', body, JSON.stringify(body, null, 2));
+        await approval('Save this scoped request for review? Source access and candidate saving need separate approval.', options);
+        await remember(scope, campaign, null, body, options, output);
+        return;
+    }
+    let change = args[2] ? identifier(args[2]) : undefined;
+    if (!change && interactive)
+        change = identifier((await choosePage('Saved source change', path, scope, { ...options, search: undefined }, row => ({ label: row.title, detail: row.state }), page => changePage(path, scope, options, page))).id);
+    if (!change)
+        throw new CliError('agent_change_required', 'Pass a saved source-change ID.', 2);
+    const detail = path + '/' + change;
+    const row = await api(detail, auth(scope, options));
+    if (!sourceChangeMatches(row, scope.workspace, campaign, change) || !Array.isArray(row.draft_files))
+        throw new CliError('agent_change_unavailable', 'The scoped source-change response could not be confirmed.');
+    output('agent_change', row, description(row));
+    if (guided) {
+        const choices = [{ value: 'done', label: 'Done' }];
+        if (row.current) {
+            if (row.draft_files?.length)
+                choices.push({ value: 'diff', label: 'Read actual source diffs' });
+            if (row.state === 'pending')
+                choices.push({ value: 'approve', label: 'Allow drafting for selected files' });
+            if (row.state === 'approved' && row.approved_by_id === scope.owner)
+                choices.push({ value: 'resume-draft', label: 'Request continued drafting' });
+            if (row.state === 'drafted')
+                choices.push({ value: 'accept', label: 'Review diff and save candidate' });
+            if (row.state === 'creating' && row.problem)
+                choices.push({ value: 'retry-save', label: 'Retry the failed candidate save' });
+            if (row.state === 'accepted') {
+                choices.push({ value: 'copy', label: 'Download candidate to a separate local folder' });
+                if (row.comparison_available)
+                    choices.push({ value: 'compare', label: 'Prepare control and candidate comparison' });
+            }
+        }
+        if (row.state === 'accepted')
+            choices.push({ value: 'comparisons', label: 'Read saved comparison setup and run history' });
+        if (!['accepted', 'dismissed'].includes(row.state))
+            choices.push({ value: 'dismiss', label: 'Dismiss change' });
+        const chosen = await selectOne('Source change', choices, options.signal);
+        if (chosen === 'done')
+            return;
+        action = chosen;
+    }
+    if (action === 'show')
+        return;
+    if (action === 'comparisons')
+        return comparisonHistory(detail, scope, options, output);
+    if (action === 'comparison-runs') {
+        if (!args[3])
+            throw new CliError('comparison_required', 'Pass the saved comparison ID after the change ID.', 2);
+        return comparisonHistory(detail, scope, options, output, identifier(args[3]));
+    }
+    if (action === 'compare') {
+        if (!row.comparison_available)
+            throw new CliError('agent_comparison_unavailable', 'Review a current approved source candidate before preparing comparison worlds.', 2);
+        if (row.state !== 'accepted' || !row.current || !row.draft_sha256)
+            throw new CliError('comparison_candidate_required', 'Save a reviewed, current candidate before preparing comparison worlds.', 2);
+        const body = { scope_sha256: row.scope_sha256, draft_sha256: row.draft_sha256,
+            additional_scenarios: await additionalScenarios(detail, scope, options), prepare_comparison: true };
+        output('comparison_scope', body, `Retain original scenarios, criteria, world and run settings. Add ${body.additional_scenarios.length} separately saved scenarios.\nBoth worlds need fresh connection review, validation and explicit run admission.`);
+        await approval('Prepare separate control and candidate worlds without running either agent or inheriting Vault access?', options);
+        return remember(scope, campaign, change, body, options, output, true);
+    }
+    if (action === 'diff')
+        return showDiffs(row, detail, scope, options, output, args[3]);
+    if (action === 'copy') {
+        const into = options.into ?? (interactive ? await line('New candidate folder (parent folder must exist)', 4096, options.signal) : undefined);
+        return candidateCopy(scope, campaign, change, { ...options, into }, output);
+    }
+    if (!MUTATIONS.includes(action))
+        return;
+    const body = { action: serverAction(action), scope_sha256: row.scope_sha256 };
+    if (action === 'accept') {
+        if (row.state !== 'drafted' || !row.current || !row.draft_sha256)
+            throw new CliError('agent_change_draft_required', 'Review a current completed draft before saving a candidate.');
+        if (interactive)
+            await showDiffs(row, detail, scope, options, output);
+        else if (options.reviewedDraft !== row.draft_sha256)
+            throw new CliError('agent_change_review_required', 'Inspect changes <campaign> diff <change> first, then supply --reviewed-draft <exact-sha256> and --approve-change.', 2);
+        if (options.reviewedDraft && options.reviewedDraft !== row.draft_sha256)
+            throw new CliError('agent_change_draft_changed', 'The reviewed draft changed. Inspect the current diff before accepting.', 2);
+        body.draft_sha256 = row.draft_sha256;
+        body.reviewed = true;
+    }
+    const labels = {
+        approve: 'Allow Firedrill to read and draft changes only in these files? This may use the configured model.',
+        'resume-draft': 'Continue drafting for this exact approved scope? This may use the configured model.',
+        accept: 'I reviewed the actual diff, including safety and approval behavior. Save a separate candidate without running it?',
+        'retry-save': 'Retry saving the same approved draft? This does not rerun the agent or request another draft.',
+        dismiss: 'Dismiss this source-change request and revoke further draft access?',
+    };
+    await approval(labels[action], options);
+    await remember(scope, campaign, change, body, options, output);
+}

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

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