firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/campaign-controls.js

@@ -0,0 +1,122 @@
+import { randomUUID } from 'node:crypto';
+import { createInterface } from 'node:readline/promises';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { selectedWorkspace } from './world-access.js';
+import { identifier } from './world-contracts.js';
+const direct = { pause: 'pause', 'resume-scheduling': 'resume', cancel: 'cancel' };
+const commands = new Set(['pause', 'resume', 'cancel']);
+const readActions = new Set(['control-request', 'continue-control', 'withdraw-control']);
+const terminal = new Set(['completed', 'failed', 'canceled']);
+const description = {
+    pause: 'Pause new drill dispatches. Active drills can continue; their clocks and external actions are not paused.',
+    resume: 'Resume scheduling only within the original plan, permissions and deadline. Unknown drills are not replayed.',
+    cancel: 'Request cancellation of this simulation and its remaining work. Active cleanup may take time; external effects are not rolled back.',
+};
+function checked(value, command) {
+    if (!value || value.command !== command || !['not_received', 'pending', 'accepted', 'withdrawn'].includes(value.state)
+        || value.last_error !== null && (!value.last_error || typeof value.last_error.code !== 'string' || typeof value.last_error.message !== 'string'))
+        throw new CliError('campaign_control_unconfirmed', 'The original scheduling receipt could not be confirmed. No request was repeated.');
+    return value;
+}
+async function chooseCampaign(scope, command, options) {
+    let page = 1, query = '';
+    while (true) {
+        const params = new URLSearchParams({ status: command === 'resume' ? 'resumable' : 'active', page: String(page), q: query });
+        if (options.world)
+            params.set('world', identifier(options.world));
+        const result = await api(`/api/workspaces/${scope.workspace}/simulations?${params}`, { actor: scope.owner, workspace: scope.workspace, signal: options.signal });
+        const choices = result.results.filter(row => row.status !== 'canceling' && (command !== 'pause' || row.status !== 'paused'))
+            .map(row => ({ value: row.id, label: row.name, detail: row.status }));
+        if (page > 1)
+            choices.unshift({ value: 'previous', label: 'Previous page', detail: '' });
+        if (result.next)
+            choices.push({ value: 'next', label: 'Next page', detail: '' });
+        choices.push({ value: 'search', label: 'Search simulations', detail: query }, { value: 'cancel', label: 'Cancel', detail: '' });
+        const value = await selectOne('Simulation', choices, options.signal);
+        if (value === 'next') {
+            page++;
+            continue;
+        }
+        if (value === 'previous') {
+            page--;
+            continue;
+        }
+        if (value === 'cancel')
+            throw new CliError('canceled', 'No scheduling action was submitted.', 130);
+        if (value === 'search') {
+            const prompt = createInterface({ input: process.stdin, output: process.stderr, terminal: false });
+            try {
+                query = (await prompt.question('Find a simulation (blank for all): ', { signal: options.signal })).trim();
+            }
+            finally {
+                prompt.close();
+            }
+            if (query.length > 200 || /[\u0000-\u001f\u007f-\u009f]/u.test(query))
+                throw new CliError('campaign_search_invalid', 'Use search text of up to 200 characters.', 2);
+            page = 1;
+            continue;
+        }
+        return identifier(value);
+    }
+}
+export async function campaignControl(args, options, output) {
+    const action = args[0], recover = readActions.has(action), command = recover ? args[2] : direct[action];
+    if ((!recover && !Object.hasOwn(direct, action)) || !commands.has(command) || args.length > (recover ? 4 : 2)
+        || recover && args.length !== 4 || action === 'control-request' && options.approve)
+        throw new CliError('arguments_invalid', 'Use simulation pause|resume-scheduling|cancel [id], or control-request|continue-control|withdraw-control <id> <pause|resume|cancel> <original-key>.', 2);
+    const tty = !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+    if (!args[1] && !tty)
+        throw new CliError('campaign_required', 'Provide the simulation campaign ID from saved history or its report.', 2);
+    if (!tty && action !== 'control-request' && !options.approve)
+        throw new CliError('approval_required', 'Use --approve-change for this exact reviewed scheduling request.', 2);
+    const scope = await selectedWorkspace({ ...options, interactive: tty });
+    const id = args[1] ? identifier(args[1]) : await chooseCampaign(scope, command, options);
+    const prefix = `/api/workspaces/${scope.workspace}/campaigns/${id}`;
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const current = await api(prefix, auth);
+    if (!current || current.id !== id || options.world && current.world_id !== identifier(options.world))
+        throw new CliError('campaign_scope_changed', 'The simulation does not match the selected workspace/world. Nothing was changed.', 2);
+    const key = recover ? identifier(args[3]) : randomUUID();
+    const lookup = async () => checked(await api(`${prefix}/command-requests?${new URLSearchParams({ command, request_key: key })}`, auth), command);
+    const show = (receipt) => output('campaign_control_receipt', { campaign_id: id, workspace_id: scope.workspace, request_key: key, ...receipt }, `Simulation: ${id}\nOriginal ${command} request: ${key}\n${receipt.state === 'accepted' ? 'Scheduling request accepted. This is not a claim that active work stopped or resumed.'
+        : receipt.state === 'withdrawn' ? 'This unaccepted scheduling request was discarded. No accepted action was undone.'
+            : receipt.last_error?.message ?? 'No acceptance is recorded yet. The original request may still arrive.'}`);
+    if (recover) {
+        const receipt = await lookup();
+        if (action === 'control-request' || ['accepted', 'withdrawn'].includes(receipt.state)) {
+            show(receipt);
+            return;
+        }
+    }
+    else if (terminal.has(current.state) || current.cancel_requested || command === 'resume' && !current.scheduling_paused && current.state !== 'admission_required') {
+        throw new CliError('campaign_control_unavailable', 'This simulation is not accepting that scheduling action. Inspect its current report.', 2);
+    }
+    if (!recover && command === 'pause' && current.scheduling_paused) {
+        output('campaign_already_paused', current, 'New drill scheduling is already paused. No additional action was submitted.');
+        return;
+    }
+    const withdraw = action === 'withdraw-control';
+    output('campaign_control_review', { campaign_id: id, command, request_key: key, current_state: current.state, withdraw }, `${current.name} · ${current.state}\n${withdraw ? 'Discard only this unaccepted scheduling request. If acceptance already won, it is only inspected, not undone.' : description[command]}`);
+    if (!options.approve && !await selectOne(withdraw ? 'Discard this unaccepted request?' : 'Submit this scheduling request?', [{ value: false, label: 'Keep current state' }, { value: true, label: withdraw ? 'Discard request' : 'Confirm action' }], options.signal))
+        return;
+    output('campaign_control_request', { campaign_id: id, workspace_id: scope.workspace, request_key: key, command }, `Recovery: firedrill simulation control-request ${id} ${command} ${key} --workspace ${scope.workspace}\nInspect this original key after an interrupted reply. No action is retried automatically.`);
+    if (withdraw) {
+        const body = { command, action: 'withdraw' };
+        const receipt = checked(await api(`${prefix}/command-requests`, { ...auth, method: 'POST', idempotencyKey: key,
+            body }), command);
+        if (!['accepted', 'withdrawn'].includes(receipt.state))
+            throw new CliError('campaign_control_unconfirmed', 'The original request withdrawal could not be confirmed. Inspect its printed recovery key.');
+        show(receipt);
+        return;
+    }
+    const body = { command };
+    const updated = await api(`${prefix}/commands`, { ...auth, method: 'POST', idempotencyKey: key, body });
+    if (!updated || updated.id !== id || updated.world_id !== current.world_id || updated.plan_id !== current.plan_id)
+        throw new CliError('campaign_control_unconfirmed', 'The scheduling response could not be confirmed. Inspect the printed original request.');
+    const receipt = await lookup();
+    if (receipt.state !== 'accepted')
+        throw new CliError('campaign_control_unconfirmed', 'Scheduling acceptance could not be confirmed. Inspect the printed original request.');
+    show(receipt);
+}

package/dist/cli/src/campaign-diagnoses.js

@@ -0,0 +1,118 @@
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectedWorkspace } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { terminalText } from './prompts.js';
+const names = { observed_behavior: 'Observed behavior', hypothesis: 'Possible explanation', tradeoff: 'Tradeoff',
+    acceptable_variation: 'Acceptable variation', evidence_gap: 'Missing evidence', infrastructure: 'Execution problem' };
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const invalid = () => new CliError('diagnoses_unconfirmed', 'The retained insights could not be confirmed. Reopen the simulation report.');
+const text = (value, maximum, required = false) => typeof value === 'string'
+    && Array.from(value).length <= maximum && (!required || value.trim().length > 0);
+const id = (value) => { if (typeof value !== 'string')
+    throw invalid(); return identifier(value); };
+const hash = (value) => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const changes = new Set(['use_case', 'branch', 'tests', 'setup_code', 'ready_code', 'instruction', 'call_direction', 'caller_awareness',
+    'answered_by', 'voicemail_style', 'keywords', 'sub_goals', 'variables', 'coverage', 'fixture', 'max_turns', 'persona', 'background_noise']);
+const descriptive = new Set(['coverage', 'tests', 'keywords', 'use_case', 'branch']);
+const quote = (value) => "'" + value.replaceAll("'", "'\"'\"'") + "'";
+export async function campaignDiagnoses(args, options, output) {
+    if (!args.length || args.length > 2 || !/^[1-9][0-9]{0,8}$/.test(options.page ?? '1') || (options.search ?? '').length > 200
+        || /[\u0000-\u001f\u007f-\u009f]/.test(options.search ?? '') || options.kind && !Object.hasOwn(names, options.kind))
+        throw new CliError('arguments_invalid', 'Use report <simulation-id> diagnoses [insight-id], with optional --page, --search and --kind.', 2);
+    const campaign = identifier(args[0]), detail = args[1] ? identifier(args[1]) : null;
+    const scope = await selectedWorkspace({ ...options, interactive: !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY });
+    const params = new URLSearchParams({ page: options.page ?? '1', q: options.search ?? '', kind: options.kind ?? '' });
+    const row = await api(`/api/workspaces/${scope.workspace}/campaigns/${campaign}/diagnoses${detail ? '/' + detail : '?' + params}`, { actor: scope.owner, workspace: scope.workspace, signal: options.signal });
+    const format = (value) => {
+        if (!object(value) || value.schema !== 'firedrill.simulation-diagnosis.v1' || value.campaign_id !== campaign
+            || !['retained', 'unavailable'].includes(String(value.state)) || !text(value.title, 200, true) || !Array.isArray(value.references)
+            || value.references.length > 20 || value.execution_started !== false || value.change_applied !== false
+            || !text(value.created_at, 100, true) || !Number.isFinite(Date.parse(value.created_at)))
+            throw invalid();
+        const insight = id(value.id), world = id(value.world_id);
+        const inspect = `firedrill report ${campaign} diagnoses ${insight} --workspace ${scope.workspace}`;
+        if (value.state === 'unavailable') {
+            if (value.references.length)
+                throw invalid();
+            return `Insight ${insight}\n${terminalText(value.title)}`;
+        }
+        id(value.source_id);
+        if (!Number.isSafeInteger(value.world_revision) || Number(value.world_revision) < 1
+            || typeof value.kind !== 'string' || !Object.hasOwn(names, value.kind)
+            || value.causal_status !== (value.kind === 'hypothesis' ? 'hypothesis' : 'not_established')
+            || !text(value.observation, 3000, true) || !text(value.interpretation, 3000, true)
+            || !text(value.follow_up, 2000) || !text(value.reproduction_limits, 2000)
+            || !Array.isArray(value.alternative_explanations) || value.alternative_explanations.length > 6
+            || value.alternative_explanations.some(one => !text(one, 1000, true)) || !value.references.length)
+            throw invalid();
+        const refs = value.references.map(ref => {
+            if (!object(ref) || ref.campaign_id !== campaign || !['message', 'action', 'state', 'assessment', 'execution'].includes(String(ref.kind))
+                || !text(ref.path, 2048, true) || /[\\\u0000-\u001f\u007f-\u009f]/.test(ref.path))
+                throw invalid();
+            const execution = id(ref.execution_id), record = id(ref.record_id);
+            if (ref.evidence_id !== undefined)
+                id(ref.evidence_id);
+            if (ref.comparison_id !== undefined)
+                id(ref.comparison_id);
+            const base = `/campaigns/${campaign}/trials/${execution}`;
+            const expected = ref.kind === 'message' ? base + `?view=conversation&record=${record}` : ref.kind === 'action' ? base + `?view=actions&record=${record}`
+                : ref.kind === 'assessment' ? base + `?view=assessment&assessment=${record}`
+                    : ref.kind === 'state' && ref.comparison_id ? base + `?view=state&comparison=${id(ref.comparison_id)}&change=${record}`
+                        : ref.kind === 'execution' && record === execution ? base : null;
+            if (ref.path !== expected)
+                throw invalid();
+            return `  ${terminalText(ref.kind)} ${record}: ${terminalText(ref.path)}`
+                + (ref.kind === 'message' || ref.kind === 'action'
+                    ? `\n  Read: firedrill report ${campaign} drill ${execution} ${ref.kind === 'message' ? 'messages' : 'actions'} ${record} --workspace ${scope.workspace}` : '');
+        });
+        const variation = [];
+        if (value.counterexample !== null) {
+            const draft = value.counterexample;
+            if (!object(draft) || draft.kind !== 'targeted_variation' || draft.requires_user_review !== true || draft.execution_started !== false
+                || !text(draft.title, 255, true) || !Array.isArray(draft.changes) || !draft.changes.length || draft.changes.length > changes.size)
+                throw invalid();
+            const draftId = id(draft.draft_id), baseline = id(draft.baseline_scenario_id), fields = new Set();
+            let substantive = false;
+            const edited = draft.changes.map(change => {
+                if (!object(change) || typeof change.field !== 'string' || !changes.has(change.field) || fields.has(change.field)
+                    || !Object.hasOwn(change, 'before') || !Object.hasOwn(change, 'after') || typeof change.presentation_omitted !== 'boolean'
+                    || !hash(change.before_sha256) || !hash(change.after_sha256) || change.before_sha256 === change.after_sha256)
+                    throw invalid();
+                fields.add(change.field);
+                substantive ||= !descriptive.has(change.field);
+                return change.field.replaceAll('_', ' ') + (change.presentation_omitted ? ' (inspect saved values)' : '');
+            });
+            if (!substantive)
+                throw invalid();
+            variation.push(`Targeted variation: ${terminalText(draft.title)}`, `Changed: ${edited.join(', ')}`, `Original: firedrill scenarios definition ${baseline} --world ${world} --workspace ${scope.workspace}`, `Review: firedrill scenarios draft ${draftId} --world ${world} --workspace ${scope.workspace}`, 'Adding the scenario and running it require separate review.');
+        }
+        const alternatives = value.alternative_explanations;
+        return [`${names[value.kind]} · ${insight}`, terminalText(value.title), `Observed: ${terminalText(value.observation)}`,
+            `${value.kind === 'hypothesis' ? 'Possible explanation' : 'Interpretation (cause not established)'}: ${terminalText(value.interpretation)}`,
+            value.follow_up ? `Next step: ${terminalText(value.follow_up)}` : '',
+            ...(alternatives.length ? detail ? ['Alternative explanations:', ...alternatives.map(one => `  ${terminalText(one)}`)]
+                : [`${alternatives.length} alternative explanation${alternatives.length === 1 ? '' : 's'}. Inspect this insight for details.`] : []),
+            value.reproduction_limits ? `Replay limits: ${terminalText(value.reproduction_limits)}` : '', ...variation, ...refs,
+            ...(!detail ? [`Inspect: ${inspect}`] : [])].filter(Boolean).join('\n');
+    };
+    if (detail) {
+        if (!object(row) || row.id !== detail)
+            throw invalid();
+        output('simulation_insight', row, format(row));
+    }
+    else {
+        if (!object(row) || row.campaign_id !== campaign || !Array.isArray(row.results) || row.results.length > 100
+            || !Number.isSafeInteger(row.count) || Number(row.count) < 0 || row.page !== Number(options.page ?? '1')
+            || !Number.isSafeInteger(row.page_size) || Number(row.page_size) < 1 || Number(row.page_size) > 100
+            || row.results.length > Number(row.page_size) || row.results.length !== Math.min(Number(row.page_size), Math.max(0, Number(row.count) - (Number(row.page) - 1) * Number(row.page_size)))
+            || (row.next === null) !== (Number(row.page) * Number(row.page_size) >= Number(row.count))
+            || (row.previous === null) !== (row.page === 1)
+            || row.next !== null && !text(row.next, 4096, true) || row.previous !== null && !text(row.previous, 4096, true))
+            throw invalid();
+        const next = `firedrill report ${campaign} diagnoses --workspace ${scope.workspace} --page ${Number(row.page) + 1}`
+            + (options.search ? ` --search ${quote(options.search)}` : '') + (options.kind ? ` --kind ${options.kind}` : '');
+        output('simulation_insights', row, (row.results.map(format).join('\n\n') || 'No structured insights were retained. Conversations, actions and scores remain in the report.')
+            + `\nPage ${row.page}; ${row.count} matching insights.${row.next ? `\nNext: ${next}` : ''}`);
+    }
+}