firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/world-session-checkpoints.js

@@ -0,0 +1,196 @@
+import { randomUUID } from 'node:crypto';
+import { api } from './auth.js';
+import { line } from './configuration.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { checkpointContents } from './world-checkpoint-scopes.js';
+import { sessionStateActionMatches, sessionStateRequestMatches, sessionCheckpointsPageMatches, sessionCheckpointActionsPageMatches } from '../../contracts/session-state-contracts.js';
+import { worldSessionMatches, worldSessionsPageMatches } from '../../contracts/session-contracts.js';
+export const CHECKPOINT_ACTIONS = ['checkpoints', 'checkpoint', 'restore', 'checkpoint-actions', 'checkpoint-request'];
+const text = (row) => `${row.id}  ${row.name}\n${row.available ? 'Saved' : row.state} · ${row.captured_at ?? row.created_at}`
+    + (row.record_count === null ? '' : ` · ${row.record_count} records`) + `\n${checkpointContents(row.scope)}` + (row.problem ? '\n' + row.problem : '');
+const actionText = (row) => `${row.id}  ${row.kind === 'restore' ? 'Restore' : 'Save'}${row.name ? ' · ' + row.name : ''}\n`
+    + (row.state === 'observed' ? row.kind === 'restore' ? row.restored_at ? `Restored ${row.restored_at}` : 'Restore not confirmed'
+        : row.captured ? row.checkpoint_available ? 'Saved' : 'Capture recorded; checkpoint file unavailable' : 'Not saved' : row.state) + (row.problem ? '\n' + row.problem : '');
+/** Uses the same original command intent and retained history as the browser.
+ * A lost reply is read by the original key, never a second POST or restore. */
+export async function worldSessionCheckpoints(args, options, output) {
+    const action = args[0], writing = ['checkpoint', 'restore'].includes(action);
+    if (!CHECKPOINT_ACTIONS.includes(action) || (action === 'checkpoint-request' ? args.length !== 3 : args.length > (writing ? 3 : 2))
+        || options.local !== undefined || options.managed !== undefined || options.device !== undefined || options.grant !== undefined
+        || options.seconds !== undefined || options.dataset !== undefined || options.shareDatasetWithDevice !== undefined
+        || options.checkpoint !== undefined || options.approveRealSession !== undefined || options.acknowledgeSharedState !== undefined
+        || options.name !== undefined && action !== 'checkpoint'
+        || options.run !== undefined && !writing
+        || options.shareCheckpointWithDevice !== undefined && action !== 'restore'
+        || options.page !== undefined && !['checkpoints', 'checkpoint-actions'].includes(action)
+        || options.search !== undefined && !['checkpoints', 'checkpoint-actions', 'restore'].includes(action)
+        || options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page) || (options.search?.length ?? 0) > 200) {
+        throw new CliError('arguments_invalid', 'Use sessions checkpoints, checkpoint, restore, checkpoint-actions or checkpoint-request with the matching session and options.', 2);
+    }
+    const tty = !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    const scope = await selectedWorld({ ...options, interactive: tty });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    let sessionId = args[1];
+    if (!sessionId) {
+        if (!tty)
+            throw new CliError('arguments_invalid', 'Provide the session ID from firedrill sessions.', 2);
+        let page = 1;
+        while (!sessionId) {
+            const list = await api(`${scope.prefix}/runtime-sessions?page=${page}`, auth);
+            if (!worldSessionsPageMatches(list, { actor: scope.owner, workspace: scope.workspace, world: scope.world }))
+                throw new CliError('world_session_receipt_invalid', 'Session history could not be confirmed in this world.');
+            const choices = list.results.map(row => ({ value: row.id, label: row.id, detail: `${row.execution_location} · ${row.state}` }));
+            if (page > 1)
+                choices.push({ value: 'previous', label: 'Previous page', detail: '' });
+            if (list.next)
+                choices.push({ value: 'next', label: 'Next page', detail: '' });
+            choices.push({ value: 'cancel', label: 'Cancel', detail: '' });
+            const choice = await selectOne('World session', choices, options.signal);
+            if (choice === 'cancel')
+                throw new CliError('canceled', 'No checkpoint action was submitted.', 130);
+            if (choice === 'previous')
+                page--;
+            else if (choice === 'next')
+                page++;
+            else
+                sessionId = identifier(choice);
+        }
+    }
+    sessionId = identifier(sessionId);
+    const base = `${scope.prefix}/runtime-sessions/${sessionId}`;
+    const identity = { actor: scope.owner, workspace: scope.workspace, world: scope.world, session: sessionId };
+    const kind = action === 'restore' ? 'restore' : 'save';
+    const unconfirmed = () => new CliError('world_session_acceptance_unconfirmed', 'Inspect the original checkpoint request. Its acceptance could not be confirmed; it was not resubmitted.', 2);
+    const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+    function continuation(value) {
+        return `\n\nPage ${value.page}; ${value.count.toLocaleString()} matching entries.${value.next
+            ? `\nContinue: firedrill sessions ${action} ${sessionId} --world ${scope.world} --workspace ${scope.workspace} --page ${value.page + 1}${options.search ? ' --search ' + quote(options.search) : ''}${options.json ? ' --json' : ''}` : ''}`;
+    }
+    async function lookup(key, present = true) {
+        const saved = await api(`${base}/checkpoint-intent?request_key=${identifier(key)}`, auth);
+        if (!sessionStateRequestMatches(saved, identity, key, writing ? kind : saved.request?.kind ?? 'save'))
+            throw unconfirmed();
+        if (present)
+            output('world_checkpoint_request', saved, saved.request ? actionText(saved.request)
+                : `Request ${key} is not recorded yet. A delayed original request may still arrive. Inspect it again or close the session; do not submit a replacement.`);
+        return saved;
+    }
+    if (action === 'checkpoint-request') {
+        await lookup(identifier(args[2]));
+        return;
+    }
+    if (action === 'checkpoint-actions') {
+        const page = await api(`${base}/checkpoint-actions?page=${options.page ?? '1'}&q=${encodeURIComponent(options.search ?? '')}`, auth);
+        if (!sessionCheckpointActionsPageMatches(page, identity, options.search))
+            throw unconfirmed();
+        output('world_checkpoint_actions', page, (page.results.map(actionText).join('\n\n') || 'No checkpoint actions in this session.') + continuation(page));
+        return;
+    }
+    if (action === 'checkpoints') {
+        const page = await api(`${base}/checkpoints?page=${options.page ?? '1'}&q=${encodeURIComponent(options.search ?? '')}`, auth);
+        if (!sessionCheckpointsPageMatches(page, identity, options.search))
+            throw unconfirmed();
+        output('world_checkpoints', page, (page.results.map(text).join('\n\n') || 'No matching checkpoints in this world.') + continuation(page));
+        return;
+    }
+    const session = await api(base, auth);
+    if (!worldSessionMatches(session, { actor: scope.owner, workspace: scope.workspace, world: scope.world }, { id: sessionId }))
+        throw new CliError('world_session_receipt_invalid', 'The selected session could not be confirmed.');
+    if (session.id !== sessionId || session.world_id !== scope.world || !['managed', 'local'].includes(session.execution_location)
+        || typeof session.reset_count !== 'string' || !/^(0|[1-9][0-9]{0,18})$/.test(session.reset_count)) {
+        throw new CliError('world_session_receipt_invalid', 'The selected session could not be confirmed. No checkpoint action was submitted.');
+    }
+    if (!session.can_control || session.terminal_at || !session.observation_current || !session.checkpoints_available || session.voice_call_open) {
+        throw new CliError('world_checkpoint_unavailable', 'Use a current, controllable session with checkpoint support and no open voice call.', 2);
+    }
+    let checkpoint = null, name = options.name ?? args[2];
+    if (action === 'restore') {
+        let page = 1;
+        while (!checkpoint) {
+            const data = await api(`${base}/checkpoints?page=${page}&q=${encodeURIComponent(options.search ?? '')}${args[2] ? '&checkpoint_id=' + identifier(args[2]) : ''}`, auth);
+            if (!sessionCheckpointsPageMatches(data, identity, options.search, args[2] ? identifier(args[2]) : null))
+                throw unconfirmed();
+            if (data.pending_action || data.uncertain_restore)
+                throw new CliError('world_session_request_pending', 'Inspect checkpoint activity. A preceding action is pending or uncertain; do not start another restore.', 2);
+            if (args[2]) {
+                checkpoint = data.results.find(row => row.id === identifier(args[2])) ?? null;
+                // Exact IDs use a server-side filter instead of scanning every page.
+                if (!checkpoint?.available || !checkpoint.compatible)
+                    throw new CliError('world_checkpoint_incompatible', 'Choose an available checkpoint for this exact source, configuration and schema.', 2);
+            }
+            else {
+                if (!tty)
+                    throw new CliError('arguments_invalid', 'Provide a checkpoint ID from sessions checkpoints.', 2);
+                const choices = data.results.filter(row => row.available && row.compatible).map(row => ({ value: row.id, label: row.name, detail: row.captured_at ?? row.created_at }));
+                if (page > 1)
+                    choices.push({ value: 'previous', label: 'Previous page', detail: '' });
+                if (data.next)
+                    choices.push({ value: 'next', label: 'Next page', detail: '' });
+                choices.push({ value: 'cancel', label: 'Cancel', detail: '' });
+                const choice = await selectOne('Checkpoint to restore', choices, options.signal);
+                if (choice === 'cancel')
+                    throw new CliError('canceled', 'No restore was submitted.', 130);
+                if (choice === 'previous')
+                    page--;
+                else if (choice === 'next')
+                    page++;
+                else
+                    checkpoint = data.results.find(row => row.id === choice) ?? null;
+            }
+        }
+        output('world_checkpoint_review', checkpoint, text(checkpoint));
+    }
+    else {
+        if (!name && tty)
+            name = await line('Checkpoint name', 120, options.signal);
+        if (!name?.trim() || name.length > 120 || /[\u0000-\u001f\u007f]/.test(name))
+            throw new CliError('arguments_invalid', 'Provide a checkpoint name up to 120 characters.', 2);
+        if (options.name !== undefined && args[2] !== undefined)
+            throw new CliError('arguments_invalid', 'Use a positional name or --name, not both.', 2);
+    }
+    let share = options.shareCheckpointWithDevice === true;
+    if (action === 'restore' && session.execution_location === 'local') {
+        if (!share && tty)
+            share = await selectOne('Download this checkpoint to the session’s original device?', [
+                { value: false, label: 'Cancel' }, { value: true, label: 'Allow this checkpoint download', detail: 'Private runtime input outside the project. Device copies and backups cannot be erased remotely.' }
+            ], options.signal);
+        if (!share)
+            throw new CliError('local_checkpoint_consent_required', 'Use --share-checkpoint-with-device for this exact download. --run alone is not download approval.', 2);
+    }
+    else if (share)
+        throw new CliError('arguments_invalid', 'Use --share-checkpoint-with-device only when restoring a local session.', 2);
+    if (!options.run && (!tty || !await selectOne(action === 'restore' ? 'Replace current database records and restart the agent?' : 'Briefly pause the agent and save committed database records?', [
+        { value: false, label: 'Cancel' }, { value: true, label: action === 'restore' ? 'Restore selected checkpoint' : 'Save checkpoint',
+            detail: `${checkpointContents(checkpoint?.scope ?? session.checkpoint_scope)}. Agent memory, other files and real-account changes are not included. Open tool views close.` }
+    ], options.signal))) {
+        throw new CliError('world_session_consent_required', 'No checkpoint action was submitted. Use --run to approve this exact action in automation.', 2);
+    }
+    const key = randomUUID();
+    output('world_checkpoint_request_key', { session_id: sessionId, request_key: key }, `Request: ${key}\nRecover with sessions checkpoint-request ${sessionId} ${key}. Do not repeat an uncertain restore.`);
+    let result;
+    const body = checkpoint
+        ? { expected_reset_count: session.reset_count, checkpoint_id: checkpoint.id, ...(share ? { share_checkpoint_with_device: true } : {}) }
+        : { expected_reset_count: session.reset_count, name: name };
+    const selected = { key, counter: session.reset_count, ...(checkpoint ? { checkpoint: checkpoint.id } : {}) };
+    try {
+        result = await api(`${base}/${action === 'restore' ? 'checkpoint-restore' : 'checkpoints'}`, { ...auth,
+            method: 'POST', idempotencyKey: key, body });
+    }
+    catch (error) {
+        if (options.signal.aborted)
+            throw error;
+        const saved = await lookup(key, false);
+        if (!saved.request)
+            throw new CliError('world_session_acceptance_unconfirmed', `Inspect sessions checkpoint-request ${sessionId} ${key}. No checkpoint action was resubmitted.`, 2);
+        result = saved.request;
+    }
+    if (!sessionStateActionMatches(result, identity, kind, selected))
+        throw unconfirmed();
+    const original = await lookup(key, false);
+    if (!sessionStateRequestMatches(original, identity, key, kind, selected) || original.request?.id !== result.id)
+        throw unconfirmed();
+    output('world_checkpoint_action', original.request, actionText(original.request));
+}

package/dist/cli/src/world-session-lifecycle.js

@@ -0,0 +1,207 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { requestInput } from './request-input.js';
+import { worldAllocationMatches, worldQuoteMatches, worldExtensionMatches, worldTimelineMatches, worldTimelineCanonical, worldTimelineIntentMatches, worldScheduledEventMatches, resourcePageMatches, worldCredits } from '../../contracts/world-lifetime-contracts.js';
+import { worldSessionMatches } from '../../contracts/session-contracts.js';
+import { applicationCheckpointMatches } from '../../contracts/application-state-contracts.js';
+const tty = (options) => !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+export const WORLD_LIFECYCLE_ACTIONS = ['quote', 'timelines', 'timeline-events', 'schedule', 'timeline-control', 'extension-quote', 'extend', 'extensions', 'extension-status',
+    'timeline-request', 'timeline-apply', 'timeline-withdraw',
+    'application-checkpoints', 'application-checkpoint', 'save-application-state'];
+export async function worldAllocationApproval(scope, options, selected, output) {
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    if (!tty(options) && !options.usageQuote)
+        throw new CliError('billing_quote_required', 'Use sessions quote --file selection.json, then sessions open with its --usage-quote and original --request-key.', 2);
+    const quote = options.usageQuote
+        ? await api(`/api/workspaces/${scope.workspace}/billing/usage/quotes/${identifier(options.usageQuote)}`, auth)
+        : await api(`${scope.prefix}/runtime-quotes`, { ...auth, method: 'POST', idempotencyKey: randomUUID(), body: selected });
+    if (!worldAllocationMatches(quote, scope.workspace, scope.world, selected))
+        throw new CliError('billing_scope_mismatch', 'The quote does not match this world and opening request.', 2);
+    output('world_runtime_quote', quote, `${worldCredits(quote, 'estimated')} credits estimated. Maximum budget ${worldCredits(quote)} credits. The estimate is reserved after approval.`);
+    if (tty(options) && !await selectOne('Approve runtime credits?', [{ value: false, label: 'Cancel' }, { value: true, label: 'Approve runtime' }], options.signal))
+        throw new CliError('canceled', 'No runtime was opened.', 130);
+    return quote.id;
+}
+export async function worldLifecycleCommand(args, options, output) {
+    const action = args[0], writing = ['schedule', 'timeline-control', 'timeline-apply', 'timeline-withdraw', 'extend', 'save-application-state'].includes(action), paged = ['timelines', 'timeline-events', 'extensions', 'application-checkpoints'].includes(action);
+    const expected = ['timeline-events', 'timeline-control', 'timeline-request', 'timeline-apply', 'timeline-withdraw', 'extension-status'].includes(action) ? 3 : action === 'quote' ? 1 : 2;
+    if (args.length !== expected || options.page && !paged || options.search && !['timeline-events', 'application-checkpoints'].includes(action)
+        || options.seconds && !['extension-quote', 'extend'].includes(action) || options.file && !['quote', 'schedule', 'timeline-control', 'timeline-withdraw'].includes(action)
+        || options.usageQuote && action !== 'extend' || options.request && !['quote', 'schedule', 'timeline-control', 'extend', 'save-application-state'].includes(action)
+        || options.name !== undefined && action !== 'save-application-state' || options.run !== undefined && !writing
+        || options.page && !/^[1-9][0-9]{0,8}$/.test(options.page))
+        throw new CliError('arguments_invalid', 'Use sessions quote, timelines, timeline-events, schedule, timeline-control, extensions, extension-status, extension-quote or extend with the selected session.', 2);
+    const scope = await selectedWorld({ ...options, interactive: tty(options) }), auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    if (action === 'quote') {
+        if (!options.file)
+            throw new CliError('arguments_invalid', 'Use sessions quote --file selection.json, including the original launch_request_key.', 2);
+        const selected = JSON.parse(await requestInput(options.file, options.signal));
+        const value = await api(`${scope.prefix}/runtime-quotes`, { ...auth, method: 'POST', idempotencyKey: options.request ?? randomUUID(), body: selected });
+        if (!worldAllocationMatches(value, scope.workspace, scope.world, selected))
+            throw new CliError('billing_scope_mismatch', 'The quote does not match this world.', 2);
+        output('world_runtime_quote', value, `${worldCredits(value)} credits maximum.\nUse sessions open --usage-quote ${value.id} --request-key ${selected.launch_request_key}.`);
+        return;
+    }
+    if (action === 'application-checkpoint') {
+        const key = identifier(args[1]), value = await api(`${scope.prefix}/application-checkpoints/${key}`, auth);
+        if (!applicationCheckpointMatches(value, scope.world) || value.id !== key && value.request_key !== key)
+            throw new CliError('application_checkpoint_response_invalid', 'Inspect the exact original application checkpoint.', 2);
+        output('application_checkpoint', value, `${String(value.name)}  ${String(value.state)}\n`
+            + (value.available ? `${value.components.map(one => one.name).join(', ')}\nNot included: ${value.excluded.join(', ')}.`
+                : value.state === 'pending' ? 'Waiting for the capture to finish.' : 'The saved application state is unavailable.'));
+        return;
+    }
+    const session = identifier(args[1]), base = `${scope.prefix}/runtime-sessions/${session}`;
+    const context = { id: session, world_id: scope.world, workspace_id: scope.workspace };
+    const readTimelineIntent = async (key, method = 'GET', body, selected) => {
+        const value = await api(`${base}/timelines/requests/${key}`, { ...auth, method, ...(body !== undefined ? { body } : {}) });
+        if (!worldTimelineIntentMatches(value, { ...context, actor: scope.owner }, key, selected))
+            throw new CliError('world_timeline_response_invalid', 'The original schedule action could not be confirmed. No replacement was sent.', 2);
+        return value;
+    };
+    const intentText = (value) => `${value.state}\nRequest: ${value.request_key}`
+        + (value.timeline ? `\nSchedule revision ${value.timeline.revision}: ${value.timeline.state}`
+            : value.state === 'prepared' ? '\nPrepared only. Use timeline-apply with this session and request ID to approve its application.'
+                : value.state === 'not_received' ? '\nNot recorded. A delayed prepare may still arrive. Withdraw the original before making a replacement.' : '\nNot applied. This request cannot be revived.');
+    if (['timeline-request', 'timeline-apply', 'timeline-withdraw'].includes(action)) {
+        const key = identifier(args[2]);
+        let value = await readTimelineIntent(key);
+        if (action !== 'timeline-request') {
+            if (!options.run && !(tty(options) && await selectOne(action === 'timeline-apply' ? 'Apply the exact original prepared schedule action?' : 'Withdraw the original unapplied schedule action?', [
+                { value: false, label: 'Cancel' }, { value: true, label: action === 'timeline-apply' ? 'Apply original request' : 'Withdraw original request' }
+            ], options.signal)))
+                throw new CliError('world_timeline_consent_required', 'Use --run to approve this original request action.', 2);
+            let digest = value.request_digest;
+            if (action === 'timeline-withdraw' && options.file) {
+                const saved = JSON.parse(await requestInput(options.file, options.signal));
+                if (!saved || Object.keys(saved).length !== 1 || typeof saved.request_digest !== 'string' || !/^[a-f0-9]{64}$/.test(saved.request_digest))
+                    throw new CliError('arguments_invalid', 'The withdrawal file must contain only the original request_digest from the request receipt.', 2);
+                if (digest && digest !== saved.request_digest)
+                    throw new CliError('world_timeline_response_invalid', 'The saved checksum does not match this original request.', 2);
+                digest = saved.request_digest;
+            }
+            if (action === 'timeline-withdraw' && !digest)
+                throw new CliError('world_timeline_original_body_required', 'The server has not retained this request checksum. Use --file containing only the original request_digest printed before submission, so a delayed prepare cannot revive it.', 2);
+            if (action === 'timeline-apply' && value.state === 'not_received')
+                throw new CliError('world_timeline_original_body_required', 'Prepare the exact original JSON file with its original --request-key. Nothing was applied.', 2);
+            value = await readTimelineIntent(key, action === 'timeline-apply' ? 'POST' : 'DELETE', action === 'timeline-apply' ? {} : { request_digest: digest });
+        }
+        output('world_timeline_request', value, intentText(value));
+        return;
+    }
+    const readSession = async () => {
+        const value = await api(base, auth);
+        if (!worldSessionMatches(value, { workspace: scope.workspace, world: scope.world, actor: scope.owner }, { id: session }))
+            throw new CliError('world_session_receipt_invalid', 'The selected world session could not be confirmed.', 2);
+        return value;
+    };
+    if (paged) {
+        const route = action === 'timeline-events' ? `timelines/${identifier(args[2])}/events` : action;
+        const page = Number(options.page ?? 1);
+        const value = await api(`${base}/${route}?page=${page}${options.search ? '&q=' + encodeURIComponent(options.search) : ''}`, auth);
+        if (!resourcePageMatches(value, page, one => action === 'timeline-events' ? worldScheduledEventMatches(one, args[2])
+            : action === 'timelines' ? worldTimelineMatches(one, context) : action === 'extensions' ? worldExtensionMatches(one, context)
+                : applicationCheckpointMatches(one, scope.world, { session })))
+            throw new CliError('world_lifecycle_response_invalid', 'The selected lifecycle history could not be confirmed.', 2);
+        output('world_' + action.replaceAll('-', '_'), value, value.results.map(one => `${one.id}  ${one.state}${'name' in one ? '\n' + one.name : ''}${'due_at' in one ? '\n' + one.due_at : ''}`).join('\n')
+            + `\nPage ${value.page}; ${value.count} records.${value.next ? `\nContinue with --page ${value.page + 1}` : ''}`);
+        return;
+    }
+    if (action === 'extension-status') {
+        const key = identifier(args[2]), value = await api(`${base}/extensions/${key}`, auth);
+        if (!worldExtensionMatches(value, context) || value.id !== key && value.request_key !== key)
+            throw new CliError('world_extension_response_invalid', 'Inspect the original extension for this session.', 2);
+        output('world_extension', value, `${value.state}\nUntil ${value.requested_expires_at}`);
+        return;
+    }
+    if (action === 'save-application-state') {
+        const row = await readSession();
+        if (!row.application_checkpoint.available || !row.observation_current)
+            throw new CliError('application_checkpoint_unsupported', 'This running agent has no available source-defined checkpoint API.', 2);
+        if (!options.name?.trim())
+            throw new CliError('arguments_invalid', 'Name the application checkpoint with --name.', 2);
+        output('application_checkpoint_review', row.application_checkpoint, `Source-declared components: ${row.application_checkpoint.components.map(one => one.name).join(', ')}\nNot included: ${row.application_checkpoint.excluded.join(', ')}. Controlled service state is separate.`);
+        if (!options.run && !(tty(options) && await selectOne('Save the declared application state?', [{ value: false, label: 'Cancel' }, { value: true, label: 'Save application state' }], options.signal)))
+            throw new CliError('application_checkpoint_consent_required', 'Use --run to approve this source-defined capture.', 2);
+        const key = identifier(options.request ?? randomUUID());
+        output('application_checkpoint_intent', { request_key: key }, `Request: ${key}\nRecovery: sessions application-checkpoint ${key}. Do not create another capture to recover an uncertain reply.`);
+        const value = await api(`${base}/application-checkpoints`, { ...auth, method: 'POST', idempotencyKey: key,
+            body: { name: options.name.trim(), expected_reset_count: row.reset_count, save_consent: true } });
+        if (!applicationCheckpointMatches(value, scope.world, { session, key }) || value.name !== options.name.trim())
+            throw new CliError('application_checkpoint_response_invalid', 'Inspect the exact original capture request. Nothing was repeated.', 2);
+        output('application_checkpoint', value, `${String(value.state)}\nCheckpoint ${String(value.id)}`);
+        return;
+    }
+    if (action === 'schedule' || action === 'timeline-control') {
+        if (!options.file)
+            throw new CliError('arguments_invalid', 'Provide the exact reviewed JSON request with --file.', 2);
+        const raw = await requestInput(options.file, options.signal);
+        if (!options.run && !(tty(options) && await selectOne(action === 'schedule' ? 'Approve this world event schedule?' : 'Change the pending event schedule?', [
+            { value: false, label: 'Cancel' }, { value: true, label: 'Approve schedule', detail: 'Only controlled simulated service operations. Previously sent requests remain in history.' }
+        ], options.signal)))
+            throw new CliError('world_timeline_consent_required', 'Use --run to approve the exact schedule. Nothing was changed.', 2);
+        const key = identifier(options.request ?? randomUUID());
+        const input = JSON.parse(raw);
+        const selected = { action: action === 'schedule' ? 'schedule' : 'control', timeline: action === 'schedule' ? null : identifier(args[2]) };
+        const current = await readSession();
+        const body = { action: selected.action, timeline_id: selected.timeline,
+            expected_reset_count: action === 'schedule' ? String(input.expected_reset_count ?? '') : current.reset_count, input };
+        const digest = createHash('sha256').update(worldTimelineCanonical({ world_id: scope.world, session_id: session, ...body })).digest('hex');
+        output('world_timeline_intent', { request_key: key, session_id: session, request_digest: digest }, `Request: ${key}\nChecksum: ${digest}\nRecovery: sessions timeline-request ${session} ${key} --world ${scope.world} --workspace ${scope.workspace}. Keep the original JSON file and request ID.`);
+        let receipt;
+        try {
+            receipt = await readTimelineIntent(key, 'PUT', body, selected);
+            if (receipt.state === 'prepared')
+                receipt = await readTimelineIntent(key, 'POST', {}, selected);
+        }
+        catch (error) {
+            if (options.signal.aborted)
+                throw error;
+            if (!(error instanceof CliError) || !['connection_uncertain', 'response_unavailable', 'world_timeline_response_invalid'].includes(error.code))
+                throw error;
+            try {
+                receipt = await readTimelineIntent(key, 'GET', undefined, selected);
+            }
+            catch {
+                throw new CliError('world_timeline_acceptance_unconfirmed', `Read sessions timeline-request ${session} ${key} before another request. No replacement was submitted.`, 2);
+            }
+        }
+        output('world_timeline_request', receipt, intentText(receipt));
+        return;
+    }
+    const row = await readSession();
+    if (!row.can_extend)
+        throw new CliError('world_extension_not_ready', 'This world cannot extend its runtime now.', 2);
+    const maximum = Math.max(0, Math.floor(row.maximum_extension_seconds - Math.max(0, (Date.parse(row.expires_at) - Date.now()) / 1000)));
+    if (maximum < 60)
+        throw new CliError('world_extension_not_ready', 'There is no additional runtime available in the current finite extension window.', 2);
+    const seconds = options.seconds ? Number(options.seconds) : tty(options) ? await selectOne('Additional runtime', [
+        { value: 60, label: '1 minute' }, { value: 3600, label: '1 hour' }, { value: 86400, label: '1 day' }, { value: 604800, label: '7 days' }
+    ].filter(one => one.value <= maximum), options.signal) : NaN;
+    if (!Number.isSafeInteger(seconds) || seconds < 60 || seconds > maximum)
+        throw new CliError('arguments_invalid', 'Choose additional runtime within this session’s available extension window.', 2);
+    const input = { additional_seconds: seconds, expected_expires_at: row.expires_at, reset_count: row.reset_count };
+    if (action === 'extend' && !options.usageQuote && !tty(options))
+        throw new CliError('billing_quote_required', 'Use sessions extension-quote first, then --usage-quote with --run.', 2);
+    const quote = options.usageQuote ? await api(`/api/workspaces/${scope.workspace}/billing/usage/quotes/${identifier(options.usageQuote)}`, auth)
+        : await api(`${base}/extension-quotes`, { ...auth, method: 'POST', idempotencyKey: randomUUID(), body: input });
+    if (!worldQuoteMatches(quote, scope.workspace) || quote.scope.schema !== 'firedrill.world-extension-budget.v1'
+        || quote.scope.session_id !== row.id || quote.scope.reset_count !== row.reset_count || quote.scope.expected_expires_at !== row.expires_at
+        || Date.parse(String(quote.scope.requested_expires_at)) !== Date.parse(row.expires_at) + seconds * 1000)
+        throw new CliError('billing_scope_mismatch', 'Review a current quote for this exact extension.', 2);
+    output('world_extension_quote', quote, `${worldCredits(quote)} credits maximum. Until ${String(quote.scope.requested_expires_at)}`);
+    if (action === 'extension-quote')
+        return;
+    if (!options.run && !(tty(options) && await selectOne('Approve the runtime extension?', [{ value: false, label: 'Cancel' }, { value: true, label: 'Extend runtime' }], options.signal)))
+        throw new CliError('world_extension_consent_required', 'Approve the exact extension with --run. Nothing was changed.', 2);
+    const key = identifier(options.request ?? randomUUID());
+    output('world_extension_intent', { request_key: key }, `Request: ${key}\nRecovery: sessions extension-status ${row.id} ${key}`);
+    const value = await api(`${base}/extensions`, { ...auth, method: 'POST', idempotencyKey: key, body: { ...input, extend_consent: true, usage_quote_id: quote.id } });
+    if (!worldExtensionMatches(value, row, { key, actor: scope.owner, input: { ...input, usage_quote_id: quote.id } }))
+        throw new CliError('world_extension_response_invalid', 'Inspect the exact original extension request. Nothing was repeated.', 2);
+    output('world_extension', value, `${value.state}\nInspect the original extension request before another action.`);
+}

package/dist/cli/src/world-session-requests.js

@@ -0,0 +1,215 @@
+import { randomUUID } from 'node:crypto';
+import { api } from './auth.js';
+import { line } from './configuration.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { requestInput } from './request-input.js';
+import { selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { worldSessionMatches, worldSessionsPageMatches } from '../../contracts/session-contracts.js';
+import { sessionCommandMatches, sessionCommandsPageMatches, sessionCommandRequestMatches, sessionConnectionsPageMatches, callableOperationMatches, callableOperationsPageMatches } from '../../contracts/session-command-contracts.js';
+export const SESSION_REQUEST_ACTIONS = ['call', 'connections', 'requests', 'request-show', 'request-result'];
+const VARIABLE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+function describe(row) {
+    return `${row.operation}: ${row.state}\nRequest ID: ${row.id}`
+        + (row.response ? `\n${row.protocol === 'mcp' ? row.response.mcp_is_error ? 'MCP tool error' : 'MCP response recorded' : `HTTP ${row.response.http_status}`}; ${row.response.body_size} response bytes.` : '')
+        + (row.response?.schema_status ? `\nOutput schema: ${{ matched: 'matches declaration', mismatch: 'does not match declaration', missing_structured: 'structured result missing', not_declared: 'not declared' }[row.response.schema_status] ?? 'unavailable'}.` : '')
+        + (row.evidence_withheld ? '\nSome bytes were withheld because they contained a private value.' : '')
+        + '\nManual service request, not a simulation drill.';
+}
+export async function worldSessionRequests(args, options, output) {
+    const action = args[0], tty = !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    if (args.length > (action === 'call' ? 4 : ['request-show', 'request-result'].includes(action) ? 3 : 2)
+        || options.file !== undefined && action !== 'call' || options.run && action !== 'call'
+        || options.page !== undefined && !['requests', 'connections'].includes(action)
+        || options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page) || (options.search?.length ?? 0) > 200) {
+        throw new CliError('arguments_invalid', 'Use sessions call [session] [connection] [operation], connections [session], requests [session], request-show <session> <id>, or request-result <session> <key>.', 2);
+    }
+    const scope = await selectedWorld({ ...options, interactive: tty });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const identity = { actor: scope.owner, workspace: scope.workspace, world: scope.world };
+    const prefix = `${scope.prefix}/runtime-sessions`;
+    // Every selector reads bounded server pages. Keyboard navigation never
+    // requires downloading the whole world, schema array or session history.
+    async function choose(title, path, key, text, matches) {
+        let page = 1, search = options.search ?? '';
+        while (true) {
+            const selectingSession = path.split('?')[0] === prefix;
+            const data = await api(`${path}${path.includes('?') ? '&' : '?'}page=${page}${selectingSession ? '' : '&q=' + encodeURIComponent(search)}`, auth);
+            if (selectingSession && !worldSessionsPageMatches(data, identity, action === 'call' ? 'active' : ''))
+                throw new CliError('session_scope_invalid', 'Session history could not be confirmed in this world.', 2);
+            if (matches && !matches(data, search))
+                throw new CliError('session_request_invalid', 'The selected service records could not be confirmed. Nothing was submitted.');
+            const selected = await selectOne(title, [
+                ...data.results.map(row => ({ value: 'row:' + key(row), ...text(row) })),
+                ...(page > 1 ? [{ value: '__previous__', label: 'Previous page' }] : []),
+                ...(data.next ? [{ value: '__next__', label: 'Next page' }] : []),
+                ...(!title.includes('session') ? [{ value: '__search__', label: 'Search' }] : []),
+                { value: '__cancel__', label: 'Cancel' },
+            ], options.signal);
+            if (selected === '__cancel__')
+                throw new CliError('canceled', 'No manual operation was submitted.', 130);
+            if (selected === '__next__') {
+                page++;
+                continue;
+            }
+            if (selected === '__previous__') {
+                page--;
+                continue;
+            }
+            if (selected === '__search__') {
+                search = await line('Find an entry (blank for all)', 200, options.signal);
+                page = 1;
+                continue;
+            }
+            const found = data.results.find(row => 'row:' + key(row) === selected);
+            if (!found)
+                throw new CliError('selection_changed', 'The selection changed. Nothing was submitted.', 2);
+            return found;
+        }
+    }
+    let sessionId = args[1];
+    if (!sessionId && tty)
+        sessionId = (await choose('World session', prefix + (action === 'call' ? '?state=active' : ''), row => row.id, row => ({ label: row.id, detail: row.state }))).id;
+    if (!sessionId)
+        throw new CliError('session_required', 'Provide a saved session ID from sessions list.', 2);
+    sessionId = identifier(sessionId);
+    const session = await api(`${prefix}/${sessionId}`, auth);
+    if (!worldSessionMatches(session, identity, { id: sessionId }))
+        throw new CliError('session_scope_invalid', 'Choose a session in this world.', 2);
+    const base = `${prefix}/${sessionId}`;
+    const commandScope = { ...identity, session: sessionId };
+    const query = `page=${options.page ?? '1'}&q=${encodeURIComponent(options.search ?? '')}`;
+    function emit(row) {
+        if (!sessionCommandMatches(row, commandScope))
+            throw new CliError('session_request_invalid', 'The original request could not be confirmed. It was not repeated.');
+        output('world_session_request', row, describe(row));
+    }
+    if (action === 'connections') {
+        const data = await api(`${base}/connections?${query}`, auth);
+        if (!sessionConnectionsPageMatches(data, commandScope, { query: options.search }))
+            throw new CliError('session_request_invalid', 'The selected connections could not be confirmed.');
+        output('world_session_connections', data, (data.results.map(row => `${row.variable}  ${row.protocol}  ${row.service_id}`).join('\n') || 'No matching session connections.') + continuation(data));
+        return;
+    }
+    if (action === 'requests') {
+        const data = await api(`${base}/requests?${query}`, auth);
+        if (!sessionCommandsPageMatches(data, commandScope, options.search))
+            throw new CliError('session_request_invalid', 'The request history could not be confirmed in this session.');
+        output('world_session_requests', data, (data.results.map(describe).join('\n\n') || 'No matching manual requests.') + continuation(data));
+        return;
+    }
+    function continuation(value) {
+        const quote = (one) => `'${one.replaceAll("'", "'\\''")}'`;
+        return `\nPage ${value.page}, ${value.count} matching records.${value.next
+            ? `\nContinue: firedrill sessions ${action} ${sessionId} --world ${scope.world} --workspace ${scope.workspace} --page ${value.page + 1}${options.search ? ' --search ' + quote(options.search) : ''}${options.json ? ' --json' : ''}` : ''}`;
+    }
+    if (action === 'request-show') {
+        const id = identifier(args[2] ?? ''), value = await api(`${base}/requests/${id}`, auth);
+        if (!sessionCommandMatches(value, commandScope, { id }))
+            throw new CliError('session_request_invalid', 'The selected request could not be confirmed.');
+        emit(value);
+        return;
+    }
+    async function lookup(key, present = true) {
+        const data = await api(`${base}/request-intent?request_key=${encodeURIComponent(key)}`, auth);
+        if (!sessionCommandRequestMatches(data, commandScope, key)) {
+            throw new CliError('session_request_invalid', 'The original request could not be confirmed. Do not repeat it.');
+        }
+        if (present) {
+            output('world_session_request_intent', data, `Request: ${key}\n${data.state === 'not_observed' ? 'Not observed yet. A delayed original request may still arrive. Do not submit a replacement.' : 'Original request retained.'}`);
+            if (data.request)
+                emit(data.request);
+        }
+        return data.request;
+    }
+    if (action === 'request-result') {
+        await lookup(identifier(args[2] ?? ''));
+        return;
+    }
+    if (!session.observation_current || session.state !== 'active' || session.terminal_at || !session.can_control) {
+        throw new CliError('session_not_ready', 'Wait for a current active session you can control. Nothing was submitted.', 2);
+    }
+    let connection;
+    if (args[2]) {
+        if (!VARIABLE.test(args[2]))
+            throw new CliError('connection_invalid', 'Choose an exact connection name from sessions connections.', 2);
+        const data = await api(`${base}/connections?callable_only=true&variable=${encodeURIComponent(args[2])}&page_size=2`, auth);
+        if (!sessionConnectionsPageMatches(data, commandScope, { callable: true, variable: args[2] }) || data.count !== 1 || data.results[0]?.variable !== args[2])
+            throw new CliError('connection_invalid', 'This session has no unique callable connection with that name.', 2);
+        connection = data.results[0];
+    }
+    else {
+        if (!tty)
+            throw new CliError('connection_required', 'Provide a connection name from sessions connections.', 2);
+        connection = await choose('Connection', `${base}/connections?callable_only=true`, row => row.variable, row => ({ label: row.variable, detail: row.protocol }), (value, search) => sessionConnectionsPageMatches(value, commandScope, { callable: true, query: search }));
+    }
+    const operations = `${scope.prefix}/items/${identifier(connection.service_id)}/operations?callable_only=true&protocol=${connection.protocol}`;
+    let operation;
+    if (args[3]) {
+        if (args[3].length > 255)
+            throw new CliError('operation_invalid', 'Choose a declared operation name.', 2);
+        const data = await api(`${operations}&name=${encodeURIComponent(args[3])}&page_size=2`, auth);
+        if (!callableOperationsPageMatches(data, connection.service_id, connection.protocol) || data.count !== 1 || data.results[0]?.name !== args[3])
+            throw new CliError('operation_invalid', 'No unique declared operation matches this name.', 2);
+        operation = data.results[0];
+    }
+    else {
+        if (!tty)
+            throw new CliError('operation_required', 'Provide a declared operation name.', 2);
+        operation = await choose('Operation', operations, row => row.name, row => ({ label: row.name, detail: `${row.protocol === 'mcp' ? 'MCP' : row.method} · ${row.effect}` }), value => callableOperationsPageMatches(value, connection.service_id, connection.protocol));
+    }
+    if (!callableOperationMatches(operation) || operation.protocol !== connection.protocol)
+        throw new CliError('operation_invalid', 'Choose an operation with this connection transport.', 2);
+    let file = options.file;
+    if (!file && tty)
+        file = await line(operation.protocol === 'mcp' ? 'Arguments JSON file (blank for {})' : 'Request JSON file (optional)', 4096, options.signal) || undefined;
+    const raw = await requestInput(file, options.signal);
+    const selectedRequest = { service_id: connection.service_id, variable: connection.variable, operation: operation.name };
+    let body;
+    if (operation.protocol === 'mcp')
+        body = { ...selectedRequest, arguments_base64: Buffer.from(raw).toString('base64') };
+    else {
+        const input = JSON.parse(raw);
+        if (Object.keys(input).some(key => !['path', 'headers', 'body_base64'].includes(key)))
+            throw new CliError('request_file_invalid', 'HTTP request files contain path, headers and body_base64 only.', 2);
+        const requestedPath = input.path ?? operation.route;
+        if (typeof requestedPath !== 'string')
+            throw new CliError('request_path_invalid', 'Use a declared HTTP path.', 2);
+        let path = requestedPath;
+        if (tty && /[{}]/.test(path))
+            path = await line('HTTP path with record values', 8192, options.signal, path);
+        if (/[{}]/.test(path))
+            throw new CliError('request_path_required', 'Replace route parameters in the request file path. Nothing was submitted.', 2);
+        const headers = input.headers ?? {}, bytes = input.body_base64 ?? '';
+        if (!headers || typeof headers !== 'object' || Array.isArray(headers) || Object.values(headers).some(value => typeof value !== 'string') || typeof bytes !== 'string')
+            throw new CliError('request_file_invalid', 'Use string header values and a base64 body. Nothing was submitted.', 2);
+        body = { ...selectedRequest, method: operation.method, path, headers: headers, body_base64: bytes };
+    }
+    const approved = options.run || tty && await selectOne('Send this manual service request?', [
+        { value: false, label: 'Cancel' }, { value: true, label: 'Send request', detail: `${operation.name} through ${connection.variable}. Supplied arguments enter this existing world and its private history.` },
+    ], options.signal);
+    if (!approved)
+        throw new CliError('session_request_consent_required', 'Nothing was submitted. Use --run to approve this exact request in automation.', 2);
+    const key = randomUUID();
+    output('world_session_request_intent', { request_key: key, session_id: sessionId }, `Request: ${key}\nIf interrupted, use sessions request-result ${sessionId} ${key}. Do not submit a replacement.`);
+    const matchesSelected = (value) => sessionCommandMatches(value, commandScope, { key, service: connection.service_id,
+        operation: operation.name, variable: connection.variable, protocol: operation.protocol });
+    try {
+        const value = await api(`${base}/requests`, { ...auth, method: 'POST', idempotencyKey: key, body });
+        if (!matchesSelected(value))
+            throw new CliError('session_request_unconfirmed', `Inspect sessions request-result ${sessionId} ${key}. Original acceptance is not confirmed.`, 2);
+        const saved = await lookup(key, false);
+        if (!saved || saved.id !== value.id || !matchesSelected(saved))
+            throw new CliError('session_request_unconfirmed', 'The original accepted request could not be confirmed. Nothing was repeated.', 2);
+        emit(saved);
+    }
+    catch (error) {
+        if (options.signal.aborted)
+            throw error;
+        const retained = await lookup(key, false);
+        if (!retained || !matchesSelected(retained))
+            throw new CliError('session_request_unconfirmed', `Use sessions request-result ${sessionId} ${key}. The original request was not repeated.`, 2);
+        emit(retained);
+    }
+}