firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/real-operations.js

@@ -0,0 +1,221 @@
+import { randomUUID } from 'node:crypto';
+import { open, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { api } from './auth.js';
+import { privateDirectory } from './credentials.js';
+import { readMetadata } from './configuration-intents.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { selectedWorkspace, selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { realOperationMatches, realOperationsMatch } from '../../contracts/real-operation-contracts.js';
+const names = { admitted: 'Request recorded', dispatching: 'Dispatch started', response: 'Response received',
+    not_sent: 'Not dispatched', uncertain: 'Outcome not confirmed' };
+const interactive = (options) => !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+const auth = (context, options) => ({ actor: context.owner, workspace: context.workspace, signal: options.signal });
+const path = (context, operation) => `${context.prefix}/real-operations/${identifier(operation)}`;
+const invalid = () => new CliError('real_review_intent_invalid', 'The exact review record is unavailable or differs. No operation was sent and no replacement review was created.', 2);
+const selection = (context) => ({ viewer: context.owner, workspace: context.workspace, world: context.world });
+async function readOperation(context, operation, options, key) {
+    const row = await api(path(context, identifier(operation)) + (key ? `?review_request_key=${identifier(key)}` : ''), auth(context, options));
+    if (!realOperationMatches(row, selection(context), operation, key))
+        throw invalid();
+    return row;
+}
+const location = async (scope, key) => join(await privateDirectory(), `real-review-${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(key)}.json`);
+function show(row, output) {
+    const activity = { simulation: 'Simulation', manual_session: 'Manual session', agent_startup: 'Agent startup', other: 'Other activity' }[row.activity];
+    output('real_operation', row, `${row.operation} · ${row.service_name}\n${activity ?? 'Other activity'}\n${names[row.outcome] ?? 'Outcome unavailable'} · ${row.effect === 'write' ? 'May change the real account' : 'Read'}\n`
+        + `Recorded: ${row.created_at}\nDispatch: ${row.dispatch_started_at ?? 'Not recorded'}\nHTTP: ${row.http_status ?? 'Not recorded'}\n`
+        + `Response delivered: ${row.response_delivery_confirmed_at ?? 'Not confirmed'}\nConfiguration: ${row.configuration_revision}\n`
+        + (row.reviewed_at ? `Reviewed: ${row.reviewed_at}\n` : row.requires_review ? `Review required.${row.review_available ? '' : ` Available after ${row.review_available_at}.`}\n` : '')
+        + 'Resetting or deleting this world does not undo real-account changes. HTTP is not a task-success score.');
+}
+async function saved(scope, key) {
+    let row;
+    try {
+        row = await readMetadata(await location(scope, key), true);
+    }
+    catch {
+        throw invalid();
+    }
+    if (Object.keys(row).sort().join(',') !== ['schema', 'owner', 'workspace', 'world', 'operation', 'key', 'acknowledge_external_effects', 'acknowledge_duplicate_risk'].sort().join(',')
+        || row.schema !== 'firedrill.local-real-review.v1' || row.owner !== scope.owner || row.workspace !== scope.workspace || row.key !== key
+        || typeof row.world !== 'string' || typeof row.operation !== 'string' || row.acknowledge_external_effects !== true || row.acknowledge_duplicate_risk !== true)
+        throw invalid();
+    identifier(row.world);
+    identifier(row.operation);
+    return row;
+}
+async function remember(context, row, key) {
+    const intent = { schema: 'firedrill.local-real-review.v1', owner: context.owner, workspace: context.workspace,
+        world: context.world, operation: identifier(row.id), key: identifier(key), acknowledge_external_effects: true, acknowledge_duplicate_risk: true };
+    try {
+        const file = await open(await location(context, key), 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(intent));
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'EEXIST')
+            throw error;
+        const previous = await saved(context, key);
+        if (previous.world !== intent.world || previous.operation !== intent.operation)
+            throw invalid();
+    }
+    return intent;
+}
+function receipt(row, intent) {
+    const value = row.review_receipt;
+    if (!value || row.id !== intent.operation || value.operation_id !== intent.operation || value.request_key !== intent.key
+        || !['accepted', 'not_received', 'reviewed_by_another_request'].includes(value.state)
+        || value.state !== 'not_received' && !row.reviewed_at)
+        throw invalid();
+    return value.state;
+}
+async function review(context, row, options, output) {
+    if (!row.can_review)
+        throw new CliError('admin_required', 'An administrator must review this real-account request.', 3);
+    const key = options.request ? identifier(options.request) : randomUUID();
+    if (options.request) {
+        const original = await saved(context, key);
+        if (original.world !== context.world || original.operation !== row.id)
+            throw invalid();
+        const current = await readOperation(context, row.id, options, key);
+        const state = receipt(current, original);
+        if (state !== 'not_received') {
+            show(current, output);
+            output('review_receipt', current.review_receipt, state === 'accepted' ? 'The original review was accepted. No operation was repeated.' : 'Another review was already recorded. Nothing was changed.');
+            return;
+        }
+        row = current;
+    }
+    if (!row.review_available)
+        throw new CliError('real_effect_dispatch_pending', row.reviewed_at
+            ? 'This request is already reviewed. Inspect its recorded outcome.' : row.requires_review
+            ? `The original dispatch window is still open. Review becomes available after ${row.review_available_at}.`
+            : 'This request does not need outcome review.', 2);
+    show(row, output);
+    const effects = options.effects || interactive(options) && await selectOne('Have you checked the real account and reviewed this request\'s possible effects?', [{ value: false, label: 'Cancel' }, { value: true, label: 'I checked the real account' }], options.signal);
+    const risk = effects && (options.duplicateRisk || interactive(options) && await selectOne('Another write may duplicate an earlier effect. Record review?', [{ value: false, label: 'Cancel' }, { value: true, label: 'I understand the duplicate risk' }], options.signal));
+    if (!effects || !risk)
+        throw new CliError('real_effect_review_required', 'No review was sent. Automation needs both --acknowledge-real-effects and --acknowledge-duplicate-risk after actual account review.', 2);
+    const intent = await remember(context, row, key);
+    output('review_request', { request_key: key, operation_id: row.id }, `Review request: ${key}\nIf the reply is interrupted: firedrill real-operations recover --workspace ${context.workspace} --request-key ${key}`);
+    const body = { request_key: key, acknowledge_external_effects: true, acknowledge_duplicate_risk: true };
+    const result = await api(path(context, row.id), { ...auth(context, options), method: 'POST', body });
+    if (!realOperationMatches(result, selection(context), row.id, key))
+        throw invalid();
+    if (receipt(result, intent) !== 'accepted')
+        throw invalid();
+    output('review_receipt', result.review_receipt, 'Review recorded. The original operation was not repeated or marked successful.');
+    show(result, output);
+}
+function filters(options, page, search) {
+    const values = new URLSearchParams({ page: String(page), q: search });
+    if (options.service)
+        values.set('service_id', identifier(options.service));
+    if (options.outcome) {
+        if (!Object.hasOwn(names, options.outcome))
+            throw new CliError('arguments_invalid', 'Choose admitted, dispatching, response, not_sent or uncertain.', 2);
+        values.set('outcome', options.outcome);
+    }
+    if (options.needsReview)
+        values.set('review', 'required');
+    return values;
+}
+export async function realOperationsCommand(args, options, output) {
+    if (args.length > 2 || options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page) || (options.search?.length ?? 0) > 200) {
+        throw new CliError('arguments_invalid', 'Use real-operations [list|show|review|recover|forget], scoped paging and exact request options.', 2);
+    }
+    const action = args[0] ?? 'list';
+    if (!['list', 'show', 'review', 'recover', 'forget'].includes(action)
+        || ['show', 'review'].includes(action) && !args[1] || ['list', 'recover', 'forget'].includes(action) && args[1]
+        || ['recover', 'forget'].includes(action) && !options.request
+        || action !== 'review' && (options.effects !== undefined || options.duplicateRisk !== undefined)
+        || !['review', 'recover', 'forget'].includes(action) && options.request !== undefined
+        || action !== 'list' && [options.page, options.search, options.service, options.outcome, options.needsReview].some(value => value !== undefined)) {
+        throw new CliError('arguments_invalid', 'Use list filters only for history, an operation ID for show/review, and the exact --request-key for recover/forget.', 2);
+    }
+    const selecting = interactive(options);
+    if (action === 'list')
+        filters(options, Number(options.page ?? 1), options.search ?? '');
+    if (action === 'recover' || action === 'forget') {
+        const scope = await selectedWorkspace({ ...options, interactive: selecting });
+        const intent = await saved(scope, identifier(options.request));
+        if (options.world && identifier(options.world) !== intent.world)
+            throw invalid();
+        if (action === 'forget') {
+            await unlink(await location(scope, intent.key));
+            output('review_receipt', { request_key: intent.key, local_copy_removed: true }, 'Only this terminal\'s recovery copy was removed. Any accepted or delayed review is unchanged.');
+            return;
+        }
+        const context = await selectedWorld({ ...options, expectedOwner: scope.owner, workspace: scope.workspace, world: intent.world, interactive: false });
+        const row = await readOperation(context, intent.operation, options, intent.key);
+        const state = receipt(row, intent);
+        show(row, output);
+        output('review_receipt', row.review_receipt, state === 'accepted' ? 'Original review accepted. No request was repeated.'
+            : state === 'reviewed_by_another_request' ? 'Another review was recorded. Nothing was changed.'
+                : `No accepted review receipt is visible. A delayed review may still arrive. No provider operation is resent. To explicitly retry only this same review: firedrill real-operations review ${intent.operation} --workspace ${scope.workspace} --world ${intent.world} --request-key ${intent.key}`);
+        return;
+    }
+    if (options.service)
+        identifier(options.service);
+    const context = await selectedWorld({ ...options, interactive: selecting });
+    if (action !== 'list') {
+        const row = await readOperation(context, identifier(args[1]), options);
+        if (action === 'show')
+            show(row, output);
+        else
+            await review(context, row, options, output);
+        return;
+    }
+    let page = Number(options.page ?? 1), search = options.search ?? '';
+    while (true) {
+        const result = await api(`${context.prefix}/real-operations?${filters(options, page, search)}`, auth(context, options));
+        if (!realOperationsMatch(result, selection(context), { page, query: search, outcome: options.outcome,
+            service: options.service, review: options.needsReview ? 'required' : '' }))
+            throw invalid();
+        output('real_operations', result, result.results.length ? result.results.map(row => `${row.id}  ${row.operation}  ${names[row.outcome] ?? row.outcome}${row.requires_review ? ' · Review required' : ''}  ${row.created_at}`).join('\n')
+            + `\nPage ${result.page} · ${result.count} recorded requests` : 'No matching real-account requests.');
+        if (!selecting || args[0] === 'list')
+            return;
+        const chosen = await selectOne('Real-account history', [...result.results.map(row => ({ value: row.id, label: row.operation,
+                detail: `${row.service_name} · ${row.requires_review ? 'Review required' : names[row.outcome]} · ${row.created_at}` })),
+            ...(page > 1 ? [{ value: 'previous', label: 'Previous page' }] : []), ...(result.next ? [{ value: 'next', label: 'Next page' }] : []),
+            { value: 'search', label: 'Search operations' }, { value: 'done', label: 'Back' }], options.signal);
+        if (chosen === 'done')
+            return;
+        if (chosen === 'previous') {
+            page -= 1;
+            continue;
+        }
+        if (chosen === 'next') {
+            page += 1;
+            continue;
+        }
+        if (chosen === 'search') {
+            const input = createInterface({ input: process.stdin, output: process.stderr, terminal: false });
+            try {
+                search = (await input.question('Operation name (blank for all): ', { signal: options.signal })).trim();
+            }
+            finally {
+                input.close();
+            }
+            if (search.length > 200 || /[\u0000-\u001f\u007f]/.test(search))
+                throw new CliError('arguments_invalid', 'Use an operation search up to 200 characters.', 2);
+            page = 1;
+            continue;
+        }
+        const row = await readOperation(context, identifier(chosen), options);
+        show(row, output);
+        if (row.review_available && await selectOne('Request outcome', [{ value: false, label: 'Back to history' },
+            { value: true, label: 'Review uncertain outcome' }], options.signal))
+            await review(context, row, options, output);
+    }
+}

package/dist/cli/src/recipe-intents.js

@@ -0,0 +1,58 @@
+import { createHash } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { privateDirectory } from './credentials.js';
+import { readMetadata } from './configuration-intents.js';
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+import { recipeNameMatches } from '../../contracts/world-recipe-contracts.js';
+const invalid = () => new CliError('world_recipe_intent_invalid', 'Keep the exact original saved recipe metadata. A newer world version was not substituted.', 2);
+const digest = (body) => createHash('sha256').update(JSON.stringify([body.name, body.world_revision, body.configuration_revision])).digest('hex');
+const location = async (scope, key) => join(await privateDirectory(), `recipe-${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(scope.world)}-${identifier(key)}.json`);
+function bodyMatches(value) {
+    const row = value;
+    return !!row && typeof row === 'object' && Object.keys(row).sort().join(',') === 'configuration_revision,name,world_revision'
+        && recipeNameMatches(row.name) && Number.isSafeInteger(row.world_revision) && row.world_revision > 0
+        && Number.isSafeInteger(row.configuration_revision) && row.configuration_revision > 0;
+}
+export async function retainedRecipe(scope, key) {
+    let value;
+    try {
+        value = await readMetadata(await location(scope, key), true);
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+            return null;
+        throw invalid();
+    }
+    if (Object.keys(value).sort().join(',') !== 'body,digest,key,owner,schema,workspace,world'
+        || value.schema !== 'firedrill.recipe-save-intent.v1' || value.owner !== scope.owner || value.workspace !== scope.workspace
+        || value.world !== scope.world || value.key !== key || !bodyMatches(value.body) || value.digest !== digest(value.body))
+        throw invalid();
+    return value;
+}
+export async function rememberRecipe(scope, key, body) {
+    if (!bodyMatches(body))
+        throw invalid();
+    const value = { schema: 'firedrill.recipe-save-intent.v1', owner: scope.owner, workspace: scope.workspace,
+        world: scope.world, key: identifier(key), body, digest: digest(body) };
+    try {
+        const file = await open(await location(scope, key), 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(value));
+            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 retainedRecipe(scope, key);
+        if (!prior || prior.digest !== value.digest)
+            throw invalid();
+        return prior;
+    }
+    return value;
+}

package/dist/cli/src/recorded-context-intents.js

@@ -0,0 +1,59 @@
+import { createHash } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { privateDirectory } from './credentials.js';
+import { readMetadata } from './configuration-intents.js';
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+const invalid = () => new CliError('context_original_metadata_required', 'Keep the exact original recording metadata and request ID. A different file was not substituted.', 2);
+const hash = (value) => createHash('sha256').update(JSON.stringify([value.filename, value.size, value.sha256, value.format])).digest('hex');
+const location = async (scope, key) => join(await privateDirectory(), `context-${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(scope.world)}-${identifier(key)}.json`);
+function valid(value) {
+    const row = value;
+    return !!row && typeof row === 'object' && Object.keys(row).sort().join(',') === 'content_upload_consent,filename,format,preparation_processing_consent,sha256,size'
+        && typeof row.filename === 'string' && row.filename.length <= 255 && row.filename.toLowerCase().endsWith('.json') && !/[\u0000-\u001f\u007f/\\]/.test(row.filename)
+        && Number.isSafeInteger(row.size) && row.size > 0 && row.size <= 64 * 1024 ** 2 && /^[a-f0-9]{64}$/.test(row.sha256)
+        && ['incident_json', 'otlp_json', 'langfuse_json', 'har_json'].includes(row.format)
+        && row.content_upload_consent === true && row.preparation_processing_consent === true;
+}
+export async function retainedRecording(scope, key) {
+    let value;
+    try {
+        value = await readMetadata(await location(scope, key), true);
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+            return null;
+        throw invalid();
+    }
+    if (Object.keys(value).sort().join(',') !== 'digest,key,owner,schema,upload,workspace,world'
+        || value.schema !== 'firedrill.recording-upload-intent.v1' || value.owner !== scope.owner || value.workspace !== scope.workspace
+        || value.world !== scope.world || value.key !== key || !valid(value.upload) || value.digest !== hash(value.upload))
+        throw invalid();
+    return value;
+}
+export async function rememberRecording(scope, key, upload) {
+    if (!valid(upload))
+        throw invalid();
+    const value = { schema: 'firedrill.recording-upload-intent.v1', owner: scope.owner, workspace: scope.workspace,
+        world: scope.world, key: identifier(key), upload, digest: hash(upload) };
+    try {
+        const file = await open(await location(scope, key), 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(value));
+            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 retainedRecording(scope, key);
+        if (!prior || prior.digest !== value.digest)
+            throw invalid();
+        return prior;
+    }
+    return value;
+}

package/dist/cli/src/recorded-context.js

@@ -0,0 +1,248 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { Readable } from 'node:stream';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { selectOne } from './prompts.js';
+import { rememberRecording, retainedRecording } from './recorded-context-intents.js';
+import { recordingUploadDestination, recordingMatches, recordingsMatch, recordingRequestMatches, recordedObservationsMatch } from '../../contracts/context-contracts.js';
+const formats = ['incident_json', 'otlp_json', 'langfuse_json', 'har_json'];
+const actions = new Set(['list', 'import', 'request', 'withdraw', 'show', 'records', 'resume', 'complete', 'accept', 'discover', 'remove']);
+const invalid = () => new CliError('context_receipt_unconfirmed', 'The original import could not be confirmed. Inspect its request before changing or importing it again.');
+const privateName = /(?:^|[._-])(?:authorization|cookie|set_cookie|password|passwd|api_key|apikey|access_token|refresh_token|private_key|secret)(?:$|[._-])/i;
+const privateValue = /\bBearer\s+[A-Za-z0-9._~+/-]{12,}|-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----|\b(?:sk-ant-|sk-proj-|ghp_|github_pat_)[A-Za-z0-9_-]{12,}|https?:\/\/[^\s/]+:[^\s/]+@|[?&](?:token|api_key|signature)=[^\s&#]+/i;
+function inspectLocal(bytes) {
+    let document;
+    try {
+        document = JSON.parse(new TextDecoder('utf8', { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new CliError('context_invalid_json', 'Choose a valid UTF-8 JSON export.', 2);
+    }
+    const stack = [{ value: document, depth: 0 }];
+    let count = 0;
+    while (stack.length) {
+        const { value, depth } = stack.pop();
+        if (++count > 2000000 || depth > 32)
+            throw new CliError('context_capacity_required', 'Import a smaller bounded recording.', 2);
+        if (typeof value === 'string' && privateValue.test(value))
+            throw new CliError('context_credentials_detected', 'Remove credentials from this recording before importing. No file was transferred.', 2);
+        if (value && typeof value === 'object') {
+            for (const [key, child] of Object.entries(value)) {
+                if (privateName.test(key) && child !== null && child !== '' && child !== '[redacted]' && child !== '[REDACTED]')
+                    throw new CliError('context_credentials_detected', 'Remove credentials and authentication headers before importing. No file was transferred.', 2);
+                stack.push({ value: child, depth: depth + 1 });
+            }
+        }
+    }
+}
+export async function recordedContextCommand(args, options, output, selected) {
+    const action = args[0] ?? 'list';
+    if (!actions.has(action) || args.length > 2)
+        throw new CliError('arguments_invalid', 'Use context list|import|request|withdraw|show|records|resume|complete|accept|discover|remove.', 2);
+    if (['list', 'import'].includes(action) && args.length > 1
+        || !['list', 'import', 'request'].includes(action) && args.length !== 2
+        || options.file !== undefined && !['import', 'resume'].includes(action) || options.format !== undefined && action !== 'import'
+        || options.request !== undefined && !['import', 'request', 'discover'].includes(action)
+        || (options.page !== undefined || options.search !== undefined) && !['list', 'records'].includes(action)
+        || options.approve !== undefined && !['import', 'resume', 'accept', 'discover', 'remove', 'withdraw'].includes(action))
+        throw new CliError('arguments_invalid', 'Use context import with --file, or supply the exact recording ID for a saved-record action.', 2);
+    const interactive = !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+    const scope = selected ?? await selectedWorld({ world: options.world, workspace: options.workspace, interactive,
+        signal: options.signal, openBrowser: options.openBrowser });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal }, base = scope.prefix + '/contexts';
+    const identity = { workspace: scope.workspace, world: scope.world };
+    const confirm = async (message) => {
+        if (options.approve)
+            return;
+        if (!interactive || !await selectOne(message, [{ value: false, label: 'Not now' }, { value: true, label: 'Approve' }], options.signal))
+            throw new CliError('context_approval_required', 'Review this import or change, then use --approve-change. No agent is run by this action.', 2);
+    };
+    const show = (row) => {
+        if (!recordingMatches(row))
+            throw invalid();
+        identifier(row.id);
+        output('recorded_context', row, `${row.filename}: ${row.state}. No target execution was started.`);
+    };
+    const lookup = async (key) => {
+        const row = await api(`${base}/requests/${identifier(key)}`, auth);
+        if (!recordingRequestMatches(row, identity, key))
+            throw invalid();
+        return row;
+    };
+    if (action === 'list') {
+        const page = Number(options.page ?? '1');
+        if (!Number.isSafeInteger(page) || page < 1 || page > 999999999 || (options.search?.length ?? 0) > 200)
+            throw new CliError('query_invalid', 'Use a positive page and a search of up to 200 characters.', 2);
+        const rows = await api(`${base}?${new URLSearchParams({ page: String(page), q: options.search ?? '' })}`, auth);
+        if (!recordingsMatch(rows, identity, page, options.search ?? ''))
+            throw invalid();
+        output('recorded_contexts', rows, rows.results.map(row => `${row.id}  ${row.filename}  ${row.state}`).join('\n') || 'No imported recordings. Source alone is enough to prepare.');
+        return;
+    }
+    if (action === 'request') {
+        const key = identifier(args[1] ?? options.request ?? '');
+        const row = await lookup(key);
+        output('recorded_context_request', row, `Import ${key}: ${row.state}.`);
+        return;
+    }
+    if (action === 'withdraw') {
+        const key = identifier(args[1]), original = await retainedRecording(scope, key);
+        const before = await lookup(key);
+        if (before.recording && before.recording.state !== 'uploading') {
+            show(before.recording);
+            return;
+        }
+        if (!original)
+            throw new CliError('context_original_metadata_required', 'This device does not retain the original approved file metadata. Recover its upload in the portal or use the exact API request metadata. No replacement was created.', 2);
+        await confirm('Withdraw only this original unfinished recording upload? A delayed create must not revive it.');
+        const row = await api(`${base}/requests/${key}`, { ...auth, method: 'DELETE', body: { upload: original.upload } });
+        if (!recordingRequestMatches(row, identity, key))
+            throw invalid();
+        output('recorded_context_request', row, row.recording?.state === 'revoked' ? 'Original upload withdrawn. It cannot be resumed.' : 'The original recording was already received. Inspect its status; it was not removed.');
+        return;
+    }
+    if (action === 'show' || action === 'records') {
+        const id = identifier(args[1] ?? '');
+        if (action === 'show') {
+            const row = await api(`${base}/${id}`, auth);
+            if (!recordingMatches(row, id))
+                throw invalid();
+            show(row);
+            return;
+        }
+        const page = Number(options.page ?? '1');
+        if (!Number.isSafeInteger(page) || page < 1 || page > 999999999)
+            throw new CliError('query_invalid', 'Choose a positive record page.', 2);
+        if ((options.search?.length ?? 0) > 200)
+            throw new CliError('query_invalid', 'Use a search of up to 200 characters.', 2);
+        const rows = await api(`${base}/${id}/records?page=${page}&q=${encodeURIComponent(options.search ?? '')}`, auth);
+        if (!recordedObservationsMatch(rows, identity, id, page, options.search ?? ''))
+            throw invalid();
+        output('recorded_observations', rows, rows.results.map(row => JSON.stringify(row)).join('\n') || 'No retained observations on this page.');
+        return;
+    }
+    if (action === 'accept') {
+        const id = identifier(args[1] ?? '');
+        const row = await api(`${base}/${id}`, auth);
+        if (!recordingMatches(row, id))
+            throw invalid();
+        show(row);
+        const world = await api(scope.prefix + '/preparation', auth);
+        await confirm('Use these reviewed records as untrusted preparation context? They do not authorize real actions or establish a correct outcome.');
+        show(await api(`${base}/${id}/accept`, { ...auth, method: 'POST', body: {
+                world_revision: world.basis.world_revision, preparation_processing_consent: true
+            } }));
+        return;
+    }
+    if (action === 'complete') {
+        const id = identifier(args[1] ?? '');
+        show(await api(`${base}/${id}/complete`, { ...auth, method: 'POST', body: {} }));
+        return;
+    }
+    if (action === 'discover') {
+        const id = identifier(args[1] ?? ''), key = options.request ? identifier(options.request) : randomUUID();
+        const row = await api(`${base}/${id}`, auth);
+        show(row);
+        if (row.state !== 'accepted')
+            throw new CliError('context_review_required', 'Review and accept this recording before requesting scenario drafts.', 2);
+        await confirm('Request scenario drafts from this recording and the connected source? This does not run the target.');
+        output('context_discovery_request', { context_id: id, request_key: key }, `Scenario discovery request ${key}. Keep this key to recover the original request.`);
+        const discovery = await api(scope.prefix + '/scenario-discovery', {
+            ...auth, method: 'POST', idempotencyKey: key, body: { context_id: id }
+        });
+        if (!discovery || discovery.request_key !== key || typeof discovery.state !== 'string')
+            throw invalid();
+        identifier(discovery.id);
+        output('context_scenario_discovery', discovery, `Scenario discovery ${discovery.id}: ${discovery.state}. Review with scenarios drafts. No target run started.`);
+        return;
+    }
+    if (action === 'remove') {
+        const id = identifier(args[1] ?? '');
+        await confirm('Remove this recording and revoke its use in future preparation?');
+        await api(`${base}/${id}`, { ...auth, method: 'DELETE' });
+        output('recording_removed', { id }, 'Recording removed.');
+        return;
+    }
+    let selectedFile = options.file;
+    if (!selectedFile && interactive) {
+        const { createInterface } = await import('node:readline/promises');
+        const prompt = createInterface({ input: process.stdin, output: process.stderr, terminal: true, historySize: 0 });
+        try {
+            selectedFile = (await prompt.question('Path to the JSON recording: ', { signal: options.signal })).trim();
+        }
+        finally {
+            prompt.close();
+        }
+    }
+    if (!selectedFile)
+        throw new CliError('file_required', 'Choose the original JSON export with --file. File paths and file content are not sent before approval.', 2);
+    const file = await open(selectedFile, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+        const stat = await file.stat({ bigint: true });
+        if (!stat.isFile() || stat.size < 1n || stat.size > 64n * 1024n ** 2n)
+            throw new CliError('context_capacity_required', 'Choose a regular JSON file up to 64 MiB. Narrow larger exports before importing.', 2);
+        const bytes = Buffer.alloc(Number(stat.size) + 1);
+        let size = 0;
+        while (size < bytes.length) {
+            options.signal.throwIfAborted();
+            const chunk = await file.read(bytes, size, Math.min(1024 * 1024, bytes.length - size), size);
+            if (!chunk.bytesRead)
+                break;
+            size += chunk.bytesRead;
+        }
+        if (size !== Number(stat.size))
+            throw new CliError('context_file_changed', 'The recording changed. No file was transferred.', 2);
+        const read = { bytesRead: size }, selectedBytes = bytes.subarray(0, size);
+        inspectLocal(selectedBytes);
+        const sha256 = createHash('sha256').update(selectedBytes).digest('hex');
+        output('context_local_review', { filename: basename(selectedFile), bytes: read.bytesRead, sha256, uploaded: false }, `${basename(selectedFile)}: ${read.bytesRead.toLocaleString()} bytes. Check personal data before approving. Credential checks are not a complete privacy filter.`);
+        await confirm('Upload this selected recording privately for review and optional preparation use? It cannot replay real effects or run the agent.');
+        let ticket, expectedId;
+        if (action === 'resume') {
+            const id = identifier(args[1] ?? '');
+            expectedId = id;
+            const resumed = await api(`${base}/${id}/upload`, { ...auth, method: 'POST', body: {} });
+            if (!recordingMatches(resumed, id) || resumed.state !== 'uploading' || !resumed.upload_identity || resumed.upload_identity.sha256 !== sha256 || resumed.upload_identity.size !== read.bytesRead)
+                throw invalid();
+            ticket = resumed;
+        }
+        else {
+            const format = options.format ?? (interactive ? await selectOne('Recording format', formats.map(value => ({ value,
+                label: value === 'incident_json' ? 'Incident, task or policy JSON' : value === 'otlp_json' ? 'OTLP JSON' : value === 'har_json' ? 'Sanitized HAR structural facts' : 'Langfuse observations JSON' })), options.signal) : 'incident_json');
+            if (!formats.includes(format))
+                throw new CliError('context_format_invalid', 'Choose incident_json, otlp_json, langfuse_json or har_json.', 2);
+            const key = options.request ? identifier(options.request) : randomUUID();
+            const body = { filename: basename(selectedFile), size: read.bytesRead, sha256, format: format, content_upload_consent: true, preparation_processing_consent: true };
+            await rememberRecording(scope, key, body);
+            const prior = await lookup(key);
+            if (prior.state !== 'not_retained') {
+                if (prior.recording)
+                    show(prior.recording);
+                return;
+            }
+            output('context_import_request', { request_key: key }, `Import request ${key}. Recover with context request ${key}.`);
+            ticket = await api(base, { ...auth, method: 'POST', idempotencyKey: key, body });
+            if (!recordingMatches(ticket) || ticket.state !== 'uploading' || ticket.filename !== body.filename || ticket.format !== body.format)
+                throw invalid();
+        }
+        const destination = recordingUploadDestination(ticket, scope.workspace, expectedId);
+        const current = await file.stat({ bigint: true });
+        if (current.ino !== stat.ino || current.dev !== stat.dev || current.size !== stat.size || current.mtimeNs !== stat.mtimeNs)
+            throw new CliError('context_file_changed', 'The recording changed. Inspect the original request; the file was not transferred.', 2);
+        // Send the reviewed bytes, not a reopened or possibly replaced filesystem path.
+        const response = await fetch(destination, { method: 'PUT', headers: ticket.headers, body: Readable.toWeb(Readable.from([selectedBytes])),
+            duplex: 'half', credentials: 'omit', redirect: 'error', signal: options.signal });
+        await response.body?.cancel();
+        if (![200, 201, 412].includes(response.status))
+            throw new CliError('context_upload_unknown', 'Upload was not confirmed. Inspect the original import before explicitly resuming the same file.');
+        show(await api(`${base}/${ticket.id}/complete`, { ...auth, method: 'POST', body: {} }));
+    }
+    finally {
+        await file.close();
+    }
+}