firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/tools.js

@@ -0,0 +1,306 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { Readable } from 'node:stream';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { selectedWorkspace } from './world-access.js';
+import { toolInstanceCommand } from './tool-instances.js';
+import { exportToolCommand } from './tool-command-export.js';
+import { toolDataCommand } from './tool-data.js';
+import { toolLifecycleCommand } from './tool-lifecycle.js';
+import { toolRecordsCommand } from './tool-records.js';
+import { toolDatasetCommand } from './tool-datasets.js';
+import { toolGroupCommand } from './tool-groups.js';
+import { toolGroupStateCommand } from './tool-group-state.js';
+import { toolCatalogCommand } from './tool-catalog.js';
+import { toolRuntimeCommand } from './tool-runtime.js';
+import { packageReads } from './tool-package-reads.js';
+import { toolContributionCommand } from './tool-contributions.js';
+import { nativeToolsCommand } from './simple/native-tools.js';
+import { packageRead, toolVersionMatches, toolPackageMatches, toolPackageUploadDestination } from './tool-package-contracts.js';
+const isInteractive = (options) => !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+const key = (value) => identifier(value);
+const serviceKey = (value) => {
+    if (!/^[a-z][a-z0-9_-]{0,79}$/.test(value))
+        throw new CliError('arguments_invalid', 'Choose a service key from tools services.', 2);
+    return value;
+};
+function receiptText(row) {
+    const saved = row.implementation_id ? `\nSaved version: ${row.implementation_id}` : '';
+    return `Package request ${row.request_key}: ${row.state}.${saved}${row.problem ? '\n' + row.problem : ''}`
+        + (row.state === 'uploading' && row.can_upload ? `\nResume this original with tools upload ${row.request_key} --file <same-package.zip> --approve-tool-upload. No replacement request is needed.` : '')
+        + (row.state === 'inspected' ? '\nPackage inspected. No tool instance or agent was started.' : '');
+}
+async function chosenFile(options) {
+    if (options.file)
+        return options.file;
+    if (!isInteractive(options))
+        throw new CliError('tool_package_file_required', 'Use --file <tool-package.zip>. No file was read or uploaded.', 2);
+    const prompt = createInterface({ input: process.stdin, output: process.stderr, terminal: false });
+    try {
+        const path = (await prompt.question('Tool package ZIP path: ', { signal: options.signal })).trim();
+        if (!path || /[\u0000-\u001f\u007f]/.test(path))
+            throw new CliError('tool_package_file_required', 'Choose a regular ZIP file.', 2);
+        return path;
+    }
+    finally {
+        prompt.close();
+    }
+}
+async function archive(path, maximum, signal) {
+    if (!path.toLowerCase().endsWith('.zip'))
+        throw new CliError('tool_package_file_invalid', 'Choose a ZIP tool package.', 2);
+    const before = await lstat(resolve(path));
+    if (!before.isFile() || before.isSymbolicLink() || !Number.isSafeInteger(before.size) || before.size < 1 || before.size > maximum) {
+        throw new CliError('tool_package_file_invalid', 'Choose a regular ZIP within the configured upload capacity.', 2);
+    }
+    const file = await open(resolve(path), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const held = await file.stat();
+        if (held.ino !== before.ino || held.dev !== before.dev || held.size !== before.size || held.mtimeMs !== before.mtimeMs)
+            throw new Error();
+        const digest = createHash('sha256');
+        for await (const chunk of file.createReadStream({ autoClose: false })) {
+            signal.throwIfAborted();
+            digest.update(chunk);
+        }
+        const after = await file.stat();
+        if (after.size !== held.size || after.mtimeMs !== held.mtimeMs || after.ctimeMs !== held.ctimeMs)
+            throw new Error();
+        return { file, stat: held, sha256: digest.digest('hex'), size: held.size };
+    }
+    catch {
+        await file.close();
+        throw new CliError('tool_package_file_changed', 'The selected package changed. No file was transferred.', 2);
+    }
+}
+export async function toolsCommand(args, options, output) {
+    let action = args[0];
+    if (options.category !== undefined && action !== 'catalog')
+        throw new CliError('arguments_invalid', 'Use --category only with tools catalog.', 2);
+    if (options.usageQuote !== undefined && !['start', 'add', 'reset', 'restore', 'fork', 'resume', 'extend'].includes(action))
+        throw new CliError('arguments_invalid', 'Use --usage-quote only for a single tool start, saved-data replacement or runtime extension. Group starts carry one quote per member in their input file.', 2);
+    if (options.state !== undefined && action !== 'instances')
+        throw new CliError('arguments_invalid', 'Use --state only with tools instances.', 2);
+    if (!['dataset-export', 'download'].includes(action) && (options.into !== undefined || options.approveDownload !== undefined))
+        throw new CliError('arguments_invalid', 'Use --into and --approve-download only with tools download or tools dataset-export.', 2);
+    if (action !== 'activity' && [options.before, options.after, options.anchor, options.outcome].some(one => one !== undefined)) {
+        throw new CliError('arguments_invalid', 'Use activity positions and outcome filters only with tools activity.', 2);
+    }
+    if (options.importStatus !== undefined && (action !== 'requests' || !['all', 'uploading', 'inspecting', 'inspected', 'rejected', 'withdrawn'].includes(options.importStatus))) {
+        throw new CliError('arguments_invalid', 'Use tools requests --import-status all|uploading|inspecting|inspected|rejected|withdrawn.', 2);
+    }
+    if (['contribute', 'contributions', 'contribution', 'contribution-withdraw'].includes(action))
+        return toolContributionCommand(args, options, output);
+    if (action === 'download')
+        return exportToolCommand(args, options, output);
+    if (['quote', 'extension-quote', 'extend', 'extensions', 'extension-status'].includes(action))
+        return toolRuntimeCommand(args, options, output);
+    if (['group-state', 'group-state-members', 'group-state-status', 'group-state-quote', 'capture-group', 'reset-group', 'fork-group'].includes(action))
+        return toolGroupStateCommand(args, options, output);
+    if (['catalog', 'catalog-categories', 'catalog-show', 'catalog-operations', 'catalog-operation', 'add', 'save', 'catalog-setups', 'catalog-status', 'catalog-withdraw'].includes(action))
+        return toolCatalogCommand(args, options, output);
+    if (action === 'start' && args.length === 1)
+        return toolGroupCommand(args, options, output);
+    if (['setups', 'setup', 'setup-members', 'setup-status', 'start-many', 'stop-setup'].includes(action))
+        return toolGroupCommand(args, options, output);
+    if (['start', 'start-status', 'stop', 'remove', 'removal', 'remove-status', 'connect', 'connections', 'connection-request', 'disconnect', 'open'].includes(action))
+        return toolLifecycleCommand(args, options, output);
+    if (['checkpoint', 'reset', 'restore', 'fork', 'resume', 'transitions', 'transition', 'checkpoint-status'].includes(action))
+        return toolDataCommand(args, options, output);
+    if (['instances', 'removed', 'instance', 'call', 'activity', 'result', 'checkpoints'].includes(action))
+        return toolInstanceCommand(args, options, output);
+    if (action === 'data')
+        return toolRecordsCommand(args, options, output);
+    if (['datasets', 'dataset', 'dataset-document', 'dataset-export', 'dataset-request', 'dataset-save', 'dataset-withdraw'].includes(action))
+        return toolDatasetCommand(args, options, output);
+    if (!action && isInteractive(options))
+        action = await selectOne('Tools', [
+            { value: 'start', label: 'Start tools', detail: 'Choose saved tools to run in the cloud for a set time' },
+            { value: 'sessions', label: 'Tool sessions', detail: 'Inspect, connect to or stop running tools' },
+            { value: 'catalog', label: 'Browse the tool catalog' },
+            { value: 'versions', label: 'Browse saved versions' }, { value: 'import', label: 'Import a tool package' },
+            { value: 'instances', label: 'Inspect tool instances' },
+            { value: 'download', label: 'Download retained operation content' },
+            { value: 'setups', label: 'Inspect tool setups' },
+            { value: 'remove', label: 'Remove an instance' }, { value: 'removed', label: 'Inspect removed instances' },
+        ], options.signal);
+    if (!action || ['catalog', 'add'].includes(action))
+        return toolCatalogCommand([action ?? 'catalog'], options, output);
+    if (['start-many', 'setups'].includes(action))
+        return toolGroupCommand([action], options, output);
+    if (['instances', 'removed'].includes(action))
+        return toolInstanceCommand([action], options, output);
+    if (action === 'download')
+        return exportToolCommand([action], options, output);
+    if (action === 'remove')
+        return toolLifecycleCommand(['remove'], options, output);
+    // Hosted tool sessions replace the older managed setup start.
+    if (action === 'start' || action === 'sessions')
+        return nativeToolsCommand([action], { json: options.json, workspace: options.workspace,
+            openBrowser: options.openBrowser, signal: options.signal }, output);
+    if (!['versions', 'list', 'requests', 'show', 'services', 'operations', 'operation', 'import', 'upload', 'status', 'complete', 'withdraw', 'revoke'].includes(action)
+        || args.length > (action === 'operation' ? 4 : 2)
+        || ['versions', 'list', 'requests', 'import'].includes(action) && args.length > 1
+        || !['versions', 'list', 'requests', 'services', 'operations'].includes(action) && (options.page !== undefined || options.search !== undefined)
+        || !['import', 'upload'].includes(action) && (options.file !== undefined || options.upload)
+        || action !== 'import' && options.request !== undefined
+        || !['withdraw', 'revoke'].includes(action) && options.change
+        || options.seconds !== undefined || action !== 'operations' && options.service !== undefined) {
+        throw new CliError('arguments_invalid', 'Use tools catalog, versions, show <version>, services <version>, operations <version> --service <key>, operation <version> <service> <name>, import, upload|status|complete|withdraw <request>, or revoke <version>.', 2);
+    }
+    if (options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page) || (options.search?.length ?? 0) > 200) {
+        throw new CliError('arguments_invalid', 'Use a positive page and a search up to 200 characters.', 2);
+    }
+    const scope = await selectedWorkspace({ ...options, interactive: isInteractive(options) });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const prefix = `/api/workspaces/${scope.workspace}/tools`;
+    const reads = packageReads(scope, options.signal), owner = { workspace: scope.workspace, actor: scope.owner };
+    const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+    const continuation = (page, command) => `\nPage ${page.page}; ${page.count} items.${page.next ? `\nNext: tools ${command} --workspace ${scope.workspace} --page ${page.page + 1}${options.search ? ` --search ${quote(terminalText(options.search))}` : ''}` : ''}`;
+    if (action === 'requests') {
+        const page = await reads.requests(Number(options.page ?? 1), options.search ?? '', options.importStatus ?? 'all');
+        output('tool_package_requests', page, (page.results.map(receiptText).join('\n\n') || 'No tool package requests in this workspace.')
+            + continuation(page, `requests${options.importStatus ? ` --import-status ${options.importStatus}` : ''}`));
+        return;
+    }
+    if (action === 'versions' || action === 'list') {
+        const page = await reads.versions(Number(options.page ?? 1), options.search ?? '');
+        output('tool_catalog', page, (page.results.map(row => `${row.id}  ${terminalText(row.name)} ${terminalText(row.version)} · ${row.state}\n${row.operation_count ?? 'Unrecorded'} declared operations`).join('\n\n') || 'No saved tool packages in this workspace.')
+            + continuation(page, 'versions'));
+        return;
+    }
+    if (action === 'show' || action === 'services' || action === 'operations' || action === 'operation' || action === 'revoke') {
+        const version = identifier(args[1] ?? '');
+        const original = await reads.version(version);
+        if (action === 'show') {
+            const row = original;
+            output('tool_implementation', row, `${row.name} ${row.version} · ${row.state}\n`
+                + `${row.service_count} services · ${row.operation_count} declared operations\nUse firedrill tools services ${version} to browse services.`
+                + '\nPackage information only. No instance was started.');
+        }
+        else if (action === 'services') {
+            const page = await reads.services(original, Number(options.page ?? 1), options.search ?? '');
+            output('tool_services', page, (page.results.map(one => `${one.key}: ${terminalText(one.name)} · ${one.operation_count} declared operations`).join('\n') || 'No matching services.')
+                + continuation(page, `services ${version}`));
+        }
+        else if (action === 'revoke') {
+            const approved = options.change || isInteractive(options) && await selectOne('Revoke this saved tool version?', [{ value: false, label: 'Cancel' }, { value: true, label: 'Revoke version', detail: 'Prevents new use. Saved history is not deleted.' }], options.signal);
+            if (!approved)
+                throw new CliError('tool_change_consent_required', 'No version was revoked. Use --approve-tool-change for automation.', 2);
+            const row = await api(`${prefix}/implementations/${version}`, { ...auth, method: 'DELETE' });
+            packageRead(row, toolVersionMatches(row, scope.workspace, version) && row.contract_digest === original.contract_digest && row.state === 'revoked');
+            const observed = await reads.version(version);
+            packageRead(observed, observed.contract_digest === original.contract_digest && observed.state === 'revoked');
+            output('tool_implementation', observed, `${terminalText(observed.name)} ${terminalText(observed.version)} · ${observed.state}`);
+        }
+        else {
+            const service = serviceKey(action === 'operation' ? args[2] ?? '' : options.service ?? '');
+            await reads.service(original, service);
+            if (action === 'operation') {
+                const operation = args[3] ?? '';
+                if (!/^[A-Za-z][A-Za-z0-9_.-]{0,127}$/.test(operation))
+                    throw new CliError('arguments_invalid', 'Choose an operation name from tools operations.', 2);
+                const row = await reads.operation(original, service, operation);
+                output('tool_operation', row, JSON.stringify(row, null, 2));
+            }
+            else {
+                const page = await reads.operations(original, service, Number(options.page ?? 1), options.search ?? '');
+                output('tool_operations', page, (page.results.map(one => `${terminalText(one.name)} · ${one.effect} · ${one.transport.kind}\n${terminalText(one.description)}`
+                    + (one.mcp_aliases?.length ? `\nMCP names: ${one.mcp_aliases.map(terminalText).join(', ')}` : '')).join('\n\n') || 'No matching operations.')
+                    + continuation(page, `operations ${version} --service ${service}`));
+            }
+        }
+        return;
+    }
+    if (['status', 'complete', 'withdraw'].includes(action)) {
+        const request = key(args[1] ?? '');
+        const original = await reads.request(request);
+        if (action === 'withdraw' && !(options.change || isInteractive(options) && await selectOne('Withdraw this package upload?', [{ value: false, label: 'Keep upload' }, { value: true, label: 'Withdraw upload' }], options.signal))) {
+            throw new CliError('tool_change_consent_required', 'No request was withdrawn. Use --approve-tool-change for automation.', 2);
+        }
+        let row = original;
+        if (action !== 'status') {
+            const accepted = await api(`${prefix}/package-requests/${request}${action === 'complete' ? '/complete' : ''}`, { ...auth, ...(action === 'complete' ? { method: 'POST', body: {} } : { method: 'DELETE' }) });
+            packageRead(accepted, toolPackageMatches(accepted, owner, { key: request, id: original.id, input: original }));
+            row = await reads.request(request, { id: original.id, input: original });
+        }
+        output('tool_package_request', row, receiptText(row));
+        return;
+    }
+    const path = await chosenFile(options);
+    const consent = options.upload || isInteractive(options) && await selectOne('Upload this tool package to the selected workspace?', [{ value: false, label: 'Keep file local' }, { value: true, label: 'Upload package', detail: 'Include service code and synthetic data only. Never credentials or customer data.' }], options.signal);
+    if (!consent)
+        throw new CliError('tool_upload_consent_required', 'No package was uploaded. Use --approve-tool-upload for explicit automated transfer.', 2);
+    const capacity = await reads.versions();
+    const maximum = capacity.package_capacity.upload_bytes;
+    if (!Number.isSafeInteger(maximum) || !maximum || maximum < 1)
+        throw new CliError('tool_capacity_unavailable', 'Upload capacity is unavailable. No file was transferred.');
+    const request = key(action === 'upload' ? args[1] ?? '' : options.request ?? randomUUID());
+    const chosen = await archive(path, maximum, options.signal);
+    const requestPath = `${prefix}/package-requests/${request}`;
+    try {
+        output('tool_upload_intent', { request_key: request, workspace_id: scope.workspace, sha256: chosen.sha256, size: chosen.size }, `Tool package request: ${request}\nIf interrupted, inspect tools status ${request}, then tools complete ${request}. Do not create a replacement request.`);
+        const input = { filename: basename(path), size: chosen.size, sha256: chosen.sha256, upload_consent: true };
+        let row;
+        if (action === 'upload')
+            row = await reads.request(request, { input });
+        else {
+            try {
+                const accepted = await api(`${prefix}/package-requests`, { ...auth, method: 'POST', idempotencyKey: request, body: input });
+                packageRead(accepted, toolPackageMatches(accepted, owner, { key: request, input }));
+                row = await reads.request(request, { id: accepted.id, input });
+            }
+            catch {
+                try {
+                    row = await reads.request(request, { input });
+                }
+                catch {
+                    throw new CliError('tool_package_acceptance_unconfirmed', `Import acceptance is unconfirmed. No replacement was submitted. Inspect tools status ${request} --workspace ${scope.workspace}.`);
+                }
+            }
+        }
+        if (row.state === 'uploading' || row.state === 'inspecting') {
+            // Observe the original object before any transfer. A completed original
+            // is consumed, never re-uploaded. A definite missing object remains on
+            // this exact request; an uncertain observation stops here.
+            const observed = await api(requestPath + '/complete', { ...auth, method: 'POST', body: {} });
+            packageRead(observed, toolPackageMatches(observed, owner, { key: request, id: row.id, input }));
+            row = await reads.request(request, { id: row.id, input });
+        }
+        if (row.state !== 'uploading' || !row.can_upload) {
+            output('tool_package_request', row, receiptText(row));
+            return;
+        }
+        const access = await api(requestPath + '/upload-access', { ...auth, method: 'POST', body: {} });
+        const destination = toolPackageUploadDestination(access, owner, row);
+        const current = await chosen.file.stat();
+        if (current.size !== chosen.stat.size || current.mtimeMs !== chosen.stat.mtimeMs || current.ctimeMs !== chosen.stat.ctimeMs) {
+            throw new CliError('tool_package_file_changed', 'The package changed after its checksum was captured. Nothing was transferred.');
+        }
+        let response;
+        try {
+            response = await fetch(destination, { method: 'PUT', headers: { ...access.headers, 'Content-Length': String(chosen.size) },
+                body: Readable.toWeb(chosen.file.createReadStream({ autoClose: false, start: 0 })), duplex: 'half', redirect: 'error', credentials: 'omit',
+                signal: AbortSignal.any([options.signal, AbortSignal.timeout(12 * 60 * 1000)]) });
+            await response.body?.cancel();
+        }
+        catch {
+            throw new CliError('tool_upload_uncertain', `The upload reply is unknown. Use tools complete ${request}; no file upload is retried automatically.`);
+        }
+        if (![200, 201, 412].includes(response.status))
+            throw new CliError('tool_upload_uncertain', `Upload not confirmed. Inspect tools status ${request} before another transfer.`);
+        const receipt = await api(requestPath + '/complete', { ...auth, method: 'POST', body: {} });
+        packageRead(receipt, toolPackageMatches(receipt, owner, { key: request, id: row.id, input }));
+        const observed = await reads.request(request, { id: row.id, input });
+        output('tool_package_request', observed, receiptText(observed));
+    }
+    finally {
+        await chosen.file.close();
+    }
+}

package/dist/cli/src/trial-actions.js

@@ -0,0 +1,93 @@
+import { workspaceLink } from './browser-links.js';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { identifier } from './world-contracts.js';
+const label = (row) => row.observation_source === 'target_http_json' ? `HTTP ${row.http_status}`
+    : row.observation_source === 'target_mcp' ? row.outcome === 'succeeded' ? 'MCP response' : 'MCP error'
+        : row.outcome === 'succeeded' ? 'Reported success' : row.outcome === 'refused' ? 'Refused' : 'Reported error';
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+export function validateActionOptions(options) {
+    if (options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page)
+        || (options.search?.length ?? 0) > 200 || /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/.test(options.search ?? '')
+        || options.status !== undefined && !['succeeded', 'failed', 'refused'].includes(options.status))
+        throw new CliError('arguments_invalid', 'Use a positive page, search up to 200 characters and --status succeeded|failed|refused for action lists.', 2);
+    if (options.serviceRequest !== undefined)
+        identifier(options.serviceRequest);
+}
+async function inspect(path, id, scope, options, output) {
+    const selected = identifier(id);
+    const row = await api(`${path}/actions/${selected}`, { actor: scope.owner, workspace: scope.workspace,
+        signal: options.signal, maximumResponseBytes: 16 * 1024 ** 2 });
+    if (row.id !== selected)
+        throw new CliError('trial_action_unavailable', 'This retained action could not be confirmed.');
+    output(row, [`${row.name}: ${label(row)}`,
+        ...(row.observation_source === 'target_http_json' ? ['Observed mapped HTTP request and response, not a behavior score.'] : []),
+        ...(row.observation_source === 'target_mcp' ? ['Observed MCP tools/call arguments and matching result. Protocol success is not a behavior score or proof of state changes.'] : []),
+        ...(row.observation_source === 'synthetic_handler' ? ['Returned by the simulated handler, not proof of a state mutation or business correctness.'] : []),
+        ...(row.observation_source === 'operation_policy' ? ['Firedrill refused this operation before running its handler.'] : []),
+        ...(row.observation_source === 'source_reported' ? ['Reported by the agent, not independent proof of tool execution or state changes. The timestamp is when the report was observed.'] : []),
+        row.observation_source === 'target_http_json' ? 'Request body' : 'Arguments', JSON.stringify(row.arguments, null, 2),
+        'Response', JSON.stringify(row.result, null, 2), ...(row.error ? ['Recorded error', row.error] : []),
+        ...(row.request_path ? [workspaceLink(scope.workspace, row.request_path)] : [])].join('\n'));
+}
+export async function trialActions(path, scope, interactive, options, output, supplied) {
+    validateActionOptions(options);
+    if (supplied) {
+        if (options.page !== undefined || options.search !== undefined || options.status !== undefined || options.serviceRequest !== undefined)
+            throw new CliError('arguments_invalid', 'Use filters with an action list, not one selected action.', 2);
+        await inspect(path, supplied, scope, options, output);
+        return;
+    }
+    let page = Number(options.page ?? 1);
+    let receipt = options.serviceRequest === undefined ? undefined : identifier(options.serviceRequest);
+    const parts = path.split('/');
+    const command = `firedrill report ${identifier(parts.at(-3))} drill ${identifier(parts.at(-1))} actions --workspace ${scope.workspace}`;
+    while (true) {
+        const params = new URLSearchParams({ page: String(page), q: options.search ?? '', status: options.status ?? '' });
+        if (receipt)
+            params.set('service_request', receipt);
+        const data = await api(`${path}/actions?${params}`, { actor: scope.owner, workspace: scope.workspace, signal: options.signal });
+        if (receipt && data.service_request?.id !== receipt)
+            throw new CliError('service_receipt_unavailable', 'The selected receipt filter could not be confirmed. No unfiltered history was substituted.');
+        const continuation = command + (receipt ? ` --service-request ${receipt}` : '')
+            + (options.search ? ' --search ' + quote(options.search) : '') + (options.status ? ' --status ' + options.status : '');
+        output(data, [...(data.service_request ? [`Captured actions for ${data.service_request.operation}`,
+                data.service_request.capture_supported ? 'Matched to this original request and response, not proof of which state changes it caused.'
+                    : 'Payload capture is not available for this connection or response. Inspect its receipt and drill evidence separately.'] : []),
+            ...data.results.map(row => `${row.name}: ${label(row)}\n${row.id}`), ...(!data.count ? ['No matching retained actions.'] : []),
+            `Page ${data.page}; ${data.count.toLocaleString()} retained actions.`,
+            ...(data.next ? [`Continue: ${continuation} --page ${page + 1}`] : []), 'HTTP and MCP response outcomes are not behavior scores.'].join('\n\n'));
+        if (!interactive)
+            return;
+        const choices = data.results.map(row => ({
+            value: { kind: 'action', id: row.id }, label: row.name, detail: label(row)
+        }));
+        if (page > 1)
+            choices.push({ value: { kind: 'previous' }, label: 'Previous page' });
+        if (data.next)
+            choices.push({ value: { kind: 'next' }, label: 'Next page' });
+        if (receipt)
+            choices.push({ value: { kind: 'all' }, label: 'View all drill actions' });
+        choices.push({ value: { kind: 'done' }, label: 'Done' });
+        const selected = await selectOne('Recorded action', choices, options.signal);
+        if (selected.kind === 'done')
+            return;
+        if (selected.kind === 'previous') {
+            page -= 1;
+            continue;
+        }
+        if (selected.kind === 'next') {
+            page += 1;
+            continue;
+        }
+        if (selected.kind === 'all') {
+            receipt = undefined;
+            page = 1;
+            continue;
+        }
+        if (selected.kind !== 'action')
+            throw new CliError('selection_invalid', 'Choose a retained action.', 2);
+        await inspect(path, selected.id, scope, options, output);
+    }
+}

package/dist/cli/src/trial-checkpoints.js

@@ -0,0 +1,133 @@
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { checkpointLabel, observedCellValue } from '../../contracts/trial-state-contracts.js';
+const uuid = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+export function validateCheckpointReport(args, options) {
+    if (args.length > 4 || options.status !== undefined || options.evidenceKind !== undefined || options.checkpoint !== undefined
+        || args[1] && !uuid.test(args[1]) || args[2] && args[2] !== 'mutations' && !/^[a-f0-9]{64}$/.test(args[2])
+        || args[2] === 'mutations' && args[3] !== undefined || args[3] && !uuid.test(args[3])
+        || options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page)
+        || (options.search?.length ?? 0) > 200 || /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/.test(options.search ?? '')
+        || !args[1] && options.search !== undefined || args[3] && (options.page !== undefined || options.search !== undefined))
+        throw new CliError('arguments_invalid', 'Use state checkpoints [checkpoint-id [collection-key [record-id]]], or state checkpoints <checkpoint-id> mutations. --page pages lists; --search filters collections or records.', 2);
+}
+function shown(cell) {
+    const value = observedCellValue(cell), text = typeof value === 'string' ? value : JSON.stringify(value) ?? '';
+    return text.slice(0, 600) + (text.length > 600 || 'truncated' in cell && cell.truncated ? '…' : '');
+}
+async function selection(prompt, choices, page, next, signal) {
+    if (page > 1)
+        choices.push({ value: 'previous', label: 'Previous page', detail: '' });
+    if (next)
+        choices.push({ value: 'next', label: 'Next page', detail: '' });
+    choices.push({ value: 'done', label: 'Done', detail: '' });
+    return selectOne(prompt, choices, signal);
+}
+export async function checkpointReport(args, path, command, scope, interactive, options, output) {
+    validateCheckpointReport(args, options);
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const prefix = `${path}/state-comparisons/checkpoints`, json = options.json ? ' --json' : '';
+    let selected = args[1], collection = args[2], page = Number(options.page ?? 1);
+    if (!selected) {
+        while (true) {
+            const data = await api(`${prefix}?page=${page}`, auth);
+            output(data, [...data.results.map(row => `${checkpointLabel(row)}\n${row.captured_at ?? 'Time not retained'}; ${row.status}; ${row.id}\nInspect: ${command} checkpoints ${row.id} --workspace ${scope.workspace}`),
+                ...(!data.count ? ['No public state checkpoints have been retained.'] : []),
+                `Page ${data.page}; ${data.count.toLocaleString()} observed boundaries. Controlled SQL state only, not agent memory, a score or a restorable world.`,
+                ...(data.next ? [`Continue: ${command} checkpoints --workspace ${scope.workspace} --page ${page + 1}${json}`] : [])].join('\n\n'));
+            if (!interactive || !data.count)
+                return;
+            const value = await selection('State checkpoint', data.results.map(row => ({ value: row.id, label: checkpointLabel(row), detail: row.status })), page, data.next, options.signal);
+            if (value === 'done')
+                return;
+            if (value === 'previous' || value === 'next') {
+                page += value === 'next' ? 1 : -1;
+                continue;
+            }
+            selected = identifier(value);
+            page = 1;
+            break;
+        }
+    }
+    const original = await api(`${prefix}/${identifier(selected)}`, auth);
+    if (original.id !== selected)
+        throw new CliError('trial_state_changed', 'The original checkpoint could not be confirmed. Reopen the drill.');
+    if (collection === 'mutations') {
+        const term = options.search ?? '', search = term ? ' --search ' + quote(term) : '';
+        while (true) {
+            const data = await api(`${prefix}/${selected}/mutations?${new URLSearchParams({ page: String(page), q: term })}`, auth);
+            const key = (value) => value === null ? 'Not present' : Object.entries(value).map(([name, cell]) => `${name}: ${shown(cell)}`).join('; ');
+            output({ checkpoint: original, ...data }, [checkpointLabel(original), 'Actual committed row writes. They may cancel in the net diff; native transaction identity is scoped to this isolated attempt.',
+                ...(data.producer_origin === 'customer_device' ? ['Device-reported receipts, not independently attested managed execution.'] : []),
+                ...data.results.map(row => `${row.collection}: native transaction ${row.transaction}\nOperation request: ${row.request_id}\nPrevious key: ${key(row.key)}\nFollowing key: ${key(row.after_key)}`),
+                ...(!data.count ? ['No matching committed write receipts.'] : []), `Page ${data.page}; ${data.count.toLocaleString()} retained row writes.`,
+                ...(data.next ? [`Continue: ${command} checkpoints ${selected} mutations --workspace ${scope.workspace} --page ${page + 1}${search}${json}`] : [])].join('\n\n'));
+            if (!interactive)
+                return;
+            const value = await selection('Committed write receipts', [], page, data.next, options.signal);
+            if (value === 'done')
+                return;
+            page += value === 'next' ? 1 : -1;
+        }
+    }
+    if (original.status !== 'observed') {
+        output(original, `${checkpointLabel(original)}: state unavailable (${original.reason ?? 'not observed'}). No empty state is inferred.`);
+        return;
+    }
+    const coverage = original.omitted_checkpoints || original.omitted_cause_references
+        ? [`Observation budget: ${original.omitted_checkpoints} intermediate boundaries and ${original.omitted_cause_references} cause references omitted. Missing state is not inferred.`] : [];
+    const term = options.search ?? '', search = term ? ' --search ' + quote(term) : '';
+    if (!collection) {
+        while (true) {
+            const data = await api(`${prefix}/${selected}/collections?${new URLSearchParams({ page: String(page), q: term })}`, auth);
+            output({ checkpoint: original, ...data }, [checkpointLabel(original), ...coverage,
+                ...(original.kind === 'operation_committed' ? [`Committed write receipts: ${command} checkpoints ${selected} mutations --workspace ${scope.workspace}`] : []),
+                ...data.results.map(row => `${row.name}: ${row.row_count.toLocaleString()} records; ${row.column_count} fields\n${row.key}\nRead: ${command} checkpoints ${selected} ${row.key} --workspace ${scope.workspace}`),
+                ...(!data.count ? ['No matching observed collections.'] : []), `Page ${data.page}; ${data.count.toLocaleString()} collections.`,
+                ...(data.next ? [`Continue: ${command} checkpoints ${selected} --workspace ${scope.workspace} --page ${page + 1}${search}${json}`] : [])].join('\n\n'));
+            if (!interactive || !data.count)
+                return;
+            const value = await selection('Observed collection', data.results.map(row => ({ value: row.key, label: row.name, detail: `${row.row_count} records` })), page, data.next, options.signal);
+            if (value === 'done')
+                return;
+            if (value === 'previous' || value === 'next') {
+                page += value === 'next' ? 1 : -1;
+                continue;
+            }
+            collection = value;
+            page = 1;
+            break;
+        }
+    }
+    const records = `${prefix}/${selected}/collections/${collection}/records`;
+    const showRecord = async (record) => {
+        const value = await api(`${records}/${identifier(record)}`, { ...auth, maximumResponseBytes: 16 * 1024 ** 2 });
+        if (value.id !== record)
+            throw new CliError('trial_state_changed', 'The original state record could not be confirmed. Reopen the checkpoint.');
+        output(value, [`Record ${(value.position + 1).toLocaleString()}`, ...Object.entries(value.cells).slice(0, 40).map(([name, cell]) => `${name}: ${shown(cell)}`),
+            ...(Object.keys(value.cells).length > 40 ? ['Display shortened. Use --json for the complete retained record.'] : [])].join('\n'));
+    };
+    if (args[3]) {
+        await showRecord(args[3]);
+        return;
+    }
+    while (true) {
+        const data = await api(`${records}?${new URLSearchParams({ page: String(page), q: term })}`, auth);
+        output({ checkpoint: original, ...data }, [...data.results.map(row => `Record ${(row.position + 1).toLocaleString()}: ${Object.entries(row.cells).slice(0, 3).map(([name, cell]) => `${name}: ${shown(cell)}`).join('; ')}\nRead: ${command} checkpoints ${selected} ${collection} ${row.id} --workspace ${scope.workspace}`),
+            ...(!data.count ? ['No matching observed records.'] : []), `Page ${data.page}; ${data.count.toLocaleString()} records. Directory values are previews.`,
+            ...(data.next ? [`Continue: ${command} checkpoints ${selected} ${collection} --workspace ${scope.workspace} --page ${page + 1}${search}${json}`] : [])].join('\n\n'));
+        if (!interactive || !data.count)
+            return;
+        const value = await selection('Observed record', data.results.map(row => ({ value: row.id, label: `Record ${row.position + 1}`, detail: row.id })), page, data.next, options.signal);
+        if (value === 'done')
+            return;
+        if (value === 'previous' || value === 'next') {
+            page += value === 'next' ? 1 : -1;
+            continue;
+        }
+        await showRecord(value);
+    }
+}

package/dist/cli/src/trial-checks.js

@@ -0,0 +1,70 @@
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { identifier } from './world-contracts.js';
+const outcomes = { met: 'Met', unmet: 'Unmet', unassessed: 'Not assessed' };
+const kinds = { objective: 'Objective check', semantic: 'Judged check', both: 'Objective and judged check', unknown: 'Check definition unavailable' };
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+export function validateCheckOptions(options) {
+    if (options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page)
+        || (options.search?.length ?? 0) > 200 || /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/.test(options.search ?? '')
+        || options.status !== undefined && !Object.hasOwn(outcomes, options.status)
+        || options.evidenceKind !== undefined && !Object.hasOwn(kinds, options.evidenceKind))
+        throw new CliError('arguments_invalid', 'Use a positive page, search up to 200 characters, --status met|unmet|unassessed and --kind objective|semantic|both|unknown for recorded check lists.', 2);
+}
+async function inspect(path, position, scope, options, output) {
+    if (!/^[1-9][0-9]{0,8}$/.test(position))
+        throw new CliError('arguments_invalid', 'Choose the original positive check position from this drill.', 2);
+    const row = await api(`${path}/checks/${position}`, { actor: scope.owner, workspace: scope.workspace,
+        signal: options.signal, maximumResponseBytes: 16 * 1024 ** 2 });
+    if (row.position !== Number(position))
+        throw new CliError('trial_check_unavailable', 'The selected original check could not be confirmed.');
+    output(row, [`${row.name}: ${outcomes[row.outcome]}`, kinds[row.kind], ...(row.reason === null ? [] : [row.reason])].join('\n'));
+}
+export async function trialRecordedChecks(path, scope, interactive, options, output, supplied) {
+    validateCheckOptions(options);
+    if (supplied) {
+        if (options.page !== undefined || options.search !== undefined || options.status !== undefined || options.evidenceKind !== undefined)
+            throw new CliError('arguments_invalid', 'Use filters with the recorded check list, not one selected check.', 2);
+        await inspect(path, supplied, scope, options, output);
+        return;
+    }
+    let page = Number(options.page ?? 1);
+    const parts = path.split('/');
+    const command = `firedrill report ${identifier(parts.at(-3))} drill ${identifier(parts.at(-1))} checks --workspace ${scope.workspace}`;
+    while (true) {
+        const params = new URLSearchParams({ page: String(page), q: options.search ?? '', status: options.status ?? '', kind: options.evidenceKind ?? '' });
+        const data = await api(`${path}/checks?${params}`, { actor: scope.owner, workspace: scope.workspace, signal: options.signal });
+        const continuation = command + (options.search ? ' --search ' + quote(options.search) : '')
+            + (options.status ? ' --status ' + options.status : '') + (options.evidenceKind ? ' --kind ' + options.evidenceKind : '') + (options.json ? ' --json' : '');
+        output(data, [...data.results.map(row => `${row.position}. ${row.name}: ${outcomes[row.outcome]}\n${kinds[row.kind]}${row.reason_excerpt === null ? '' : '\n' + row.reason_excerpt}${row.reason_truncated ? `\nRead full explanation: ${command.split(' --workspace')[0]} ${row.position} --workspace ${scope.workspace}` : ''}`),
+            ...(!data.count ? [!data.recorded_checks.result_retained ? 'The original result is not available.'
+                    : options.search || options.status || options.evidenceKind ? 'No recorded checks match these filters.' : 'No checks were included in this result.'] : []),
+            `Page ${data.page}; ${data.count.toLocaleString()} matching recorded checks.`,
+            ...(data.next ? [`Continue: ${continuation} --page ${page + 1}`] : [])].join('\n\n'));
+        if (!interactive)
+            return;
+        const choices = data.results.map(row => ({
+            value: { kind: 'check', position: row.position }, label: row.name, detail: `${outcomes[row.outcome]}; ${kinds[row.kind]}`
+        }));
+        if (page > 1)
+            choices.push({ value: { kind: 'previous' }, label: 'Previous page' });
+        if (data.next)
+            choices.push({ value: { kind: 'next' }, label: 'Next page' });
+        choices.push({ value: { kind: 'done' }, label: 'Done' });
+        const selected = await selectOne('Recorded check', choices, options.signal);
+        if (selected.kind === 'done')
+            return;
+        if (selected.kind === 'previous') {
+            page -= 1;
+            continue;
+        }
+        if (selected.kind === 'next') {
+            page += 1;
+            continue;
+        }
+        if (selected.kind !== 'check')
+            throw new CliError('selection_invalid', 'Choose a retained check.', 2);
+        await inspect(path, String(selected.position), scope, options, output);
+    }
+}