firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/tool-contributions.js

@@ -0,0 +1,58 @@
+import { api, openBrowser } from './auth.js';
+import { APP_ORIGIN, CliError } from './http.js';
+import { selectedWorkspace } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { selectOne } from './prompts.js';
+import { contributionRead, contributionPageRead } from '../../contracts/tool-contribution-contracts.js';
+const text = (row) => `${row.request_key} · ${row.state} · ${row.license}\nSaved version: ${row.implementation_id}`;
+/** Owner rights are reviewed in the browser. The CLI never infers sharing consent. */
+export async function toolContributionCommand(args, options, output) {
+    const action = args[0], interactive = !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    if (!['contribute', 'contributions', 'contribution', 'contribution-withdraw'].includes(action) || args.length > 2
+        || action !== 'contributions' && !args[1] || action !== 'contributions' && options.page !== undefined
+        || options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page)
+        || options.search !== undefined || options.file !== undefined || options.upload || options.request !== undefined
+        || options.service !== undefined || options.seconds !== undefined || action !== 'contribution-withdraw' && options.change) {
+        throw new CliError('arguments_invalid', 'Use tools contribute <version>, contributions [version] --page <n>, contribution <request>, or contribution-withdraw <request> --approve-tool-change.', 2);
+    }
+    const scope = await selectedWorkspace({ ...options, interactive });
+    const owner = { workspace: scope.workspace, actor: scope.owner }, auth = { ...owner, signal: options.signal };
+    const base = `/api/workspaces/${scope.workspace}/tools/contributions`;
+    const selected = args[1] ? identifier(args[1]) : undefined;
+    if (action === 'contribute' || action === 'contributions') {
+        const page = Number(options.page ?? 1);
+        const value = contributionPageRead(await api(`${base}?page=${page}${selected ? `&implementation_id=${selected}` : ''}`, auth), owner, { page, implementation: selected });
+        if (action === 'contributions') {
+            output('tool_contributions', value, (value.results.map(text).join('\n\n') || 'No private review nominations.')
+                + `\nPage ${value.page}; ${value.count} requests.${value.next ? `\nNext: firedrill tools contributions${selected ? ` ${selected}` : ''} --workspace ${scope.workspace} --page ${value.page + 1}` : ''}`);
+            return;
+        }
+        if (!value.can_nominate)
+            throw new CliError('tool_contribution_source_unavailable', 'Choose an available private tool version with current workspace write access.', 2);
+        const url = new URL(`/tools/versions/${selected}`, APP_ORIGIN);
+        url.searchParams.set('workspace', scope.workspace);
+        url.searchParams.set('contribute', '1');
+        output('tool_contribution_handoff', { action_required: 'browser_owner_consent', workspace_id: scope.workspace,
+            implementation_id: selected, browser_url: url.href, submitted: false }, `Open ${url.href}\nReview the exact source, rights, synthetic-only state and license in the browser. No source is copied or shared by this command.`);
+        if (interactive && options.openBrowser)
+            await openBrowser(url.href);
+        return;
+    }
+    const original = contributionRead(await api(`${base}/requests/${selected}`, auth), owner, { key: selected });
+    if (action === 'contribution') {
+        output('tool_contribution', original, text(original));
+        return;
+    }
+    if (!original.can_withdraw && original.state !== 'withdrawn')
+        throw new CliError('tool_contribution_already_published', 'This review cannot be withdrawn here. A published license is not revoked; contact support to request catalog withdrawal.', 2);
+    const approved = options.change || interactive && await selectOne('Withdraw this private catalog review?', [
+        { value: false, label: 'Cancel' }, { value: true, label: 'Withdraw review', detail: 'Prevents later publication from this nomination. Does not erase private source or history.' },
+    ], options.signal);
+    if (!approved)
+        throw new CliError('tool_change_consent_required', 'Nothing was withdrawn. Use --approve-tool-change for an explicit original-request withdrawal.', 2);
+    contributionRead(await api(`${base}/requests/${selected}`, { ...auth, method: 'DELETE' }), owner, { key: selected });
+    const result = contributionRead(await api(`${base}/requests/${selected}`, auth), owner, { key: selected });
+    if (result.state !== 'withdrawn')
+        throw new CliError('tool_contribution_withdrawal_unconfirmed', `Check original review ${selected} before another action.`, 2);
+    output('tool_contribution', result, text(result));
+}

package/dist/cli/src/tool-data.js

@@ -0,0 +1,116 @@
+import { randomUUID } from 'node:crypto';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { selectedWorkspace } from './world-access.js';
+import { toolLifecycleReads } from './tool-lifecycle-reads.js';
+import { toolStateReads } from './tool-state-reads.js';
+import { allocationApproval } from './tool-runtime.js';
+import { toolStateRead, toolCaptureAccepted, toolTransitionAccepted } from './tool-state-contracts.js';
+const writes = new Set(['checkpoint', 'reset', 'restore', 'fork', 'resume']);
+const interactive = (options) => !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+async function choose(path, title, describe, options, auth, allowed = () => true, read) {
+    let page = 1;
+    while (true) {
+        const result = read ? await read(page) : await api(`${path}${path.includes('?') ? '&' : '?'}page=${page}`, auth);
+        const value = await selectOne(title, [
+            ...result.results.filter(allowed).map(one => ({ value: one.id, label: describe(one) })),
+            ...(result.next ? [{ value: '__next__', label: 'Next page' }] : []), ...(page > 1 ? [{ value: '__previous__', label: 'Previous page' }] : []),
+            { value: '__cancel__', label: 'Cancel' },
+        ], options.signal);
+        if (value === '__cancel__')
+            throw new CliError('canceled', 'No new data operation was submitted.', 130);
+        if (value === '__next__')
+            page++;
+        else if (value === '__previous__')
+            page--;
+        else
+            return identifier(value);
+    }
+}
+function print(receipt, output) {
+    output('tool_data_request', receipt, `${'action' in receipt ? receipt.action : 'Data capture'}: ${receipt.state}\nRequest: ${receipt.request_key}`
+        + ('successor_id' in receipt && receipt.successor_id ? `\nNew instance: ${receipt.successor_id}. Check its current status and use its own connection credentials.` : '')
+        + (receipt.checkpoint_id ? `\nCheckpoint: ${receipt.checkpoint_id}` : '')
+        + (!('action' in receipt) && receipt.state === 'captured' && !receipt.checkpoint_available ? '\nCapture completed, but saved data is no longer available.' : '')
+        + (receipt.problem ? '\n' + receipt.problem : ''));
+    if (['failed', 'unavailable', 'canceled'].includes(receipt.state))
+        throw new CliError('tool_data_not_completed', receipt.problem ?? 'This data operation did not complete.', 2);
+}
+export async function toolDataCommand(args, options, output) {
+    const action = args[0], write = writes.has(action), receiptRead = ['checkpoint-status', 'transition'].includes(action);
+    if (!write && !receiptRead && action !== 'transitions' || args.length > 3 || options.file !== undefined || options.upload || options.service !== undefined || options.seconds !== undefined && (!write || action === 'checkpoint')
+        || action !== 'transitions' && (options.page !== undefined || options.search !== undefined)
+        || !write && (options.change || options.request !== undefined)
+        || options.usageQuote !== undefined && (!write || action === 'checkpoint')
+        || ['checkpoint', 'reset', 'resume', 'transitions'].includes(action) && args.length > 2
+        || options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page) || (options.search?.length ?? 0) > 200) {
+        throw new CliError('arguments_invalid', 'Use tools checkpoint|reset|resume [instance], restore|fork [instance] [checkpoint], transitions [instance], or checkpoint-status|transition <instance> <request>.', 2);
+    }
+    const scope = await selectedWorkspace({ ...options, interactive: interactive(options) });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const prefix = `/api/workspaces/${scope.workspace}/tools/instances`;
+    const lifecycle = toolLifecycleReads(scope, options.signal);
+    let instance = args[1] ? identifier(args[1]) : undefined;
+    if (!instance && interactive(options))
+        instance = await choose(prefix, 'Tool instance', one => `${one.name} ${one.version} · ${one.state}`, options, auth, () => true, page => lifecycle.instances(page));
+    if (!instance)
+        throw new CliError('tool_instance_required', 'Provide an instance from tools instances.', 2);
+    const path = `${prefix}/${instance}`;
+    const reads = toolStateReads(scope, instance, options.signal);
+    const selected = { workspace: scope.workspace, actor: scope.owner, instance };
+    if (action === 'transitions') {
+        const page = await reads.transitions(Number(options.page ?? 1), options.search ?? '');
+        const quote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
+        output('tool_data_transitions', page, (page.results.map(one => `${one.action}: ${one.state}\nRequest: ${one.request_key}${one.successor_id ? '\nNew instance: ' + one.successor_id : ''}`).join('\n\n') || 'No data operations in this instance.')
+            + `\nPage ${page.page}; ${page.count} requests.${page.next ? `\nNext: firedrill tools transitions ${instance} --workspace ${scope.workspace} --page ${page.page + 1}${options.search ? ' --search ' + quote(options.search) : ''}` : ''}`);
+        return;
+    }
+    if (receiptRead) {
+        if (!args[2])
+            throw new CliError('tool_request_required', 'Provide the original request ID printed before submission.', 2);
+        const receipt = action === 'checkpoint-status' ? await reads.capture(identifier(args[2])) : await reads.transition(identifier(args[2]));
+        print(receipt, output);
+        return;
+    }
+    const details = await lifecycle.instance(instance);
+    const stateless = details.data_mode === 'declared_stateless';
+    if (action === 'checkpoint' && stateless) {
+        throw new CliError('tool_state_not_applicable', 'This tool declares no persistent data to checkpoint. Use tools checkpoints to read its startup and closing records.', 2);
+    }
+    let checkpoint = args[2] ? identifier(args[2]) : undefined;
+    if (['restore', 'fork'].includes(action) && !checkpoint && interactive(options))
+        checkpoint = await choose(`${path}/checkpoints`, 'Saved data', one => `${one.scope === 'declared_stateless' ? one.kind === 'baseline' ? 'Startup record' : 'Closing record' : one.kind === 'manual' ? 'Checkpoint' : one.kind === 'baseline' ? 'Starting data' : 'Data before stop'} · ${one.captured_at}`, options, auth, one => one.available, page => reads.checkpoints(page));
+    if (['restore', 'fork'].includes(action) && !checkpoint)
+        throw new CliError('tool_checkpoint_required', 'Choose saved data from tools checkpoints.', 2);
+    const explanation = stateless ? action === 'fork'
+        ? 'Start separate isolated processes? The current instance stays unchanged. No persistent data or service memory is copied.'
+        : 'Start fresh isolated processes? Previous connections close. No persistent data or service memory is restored.'
+        : action === 'checkpoint' ? 'Retain a private copy of supported tool data?'
+            : action === 'fork' ? 'Start a separate instance from this saved data? The original instance stays unchanged.'
+                : 'Stop the old instance and start from saved data? Existing connections close and must be configured again.';
+    const approved = options.change || interactive(options) && await selectOne(explanation, [{ value: false, label: 'Cancel' }, { value: true, label: action === 'checkpoint' ? 'Save checkpoint' : 'Continue' }], options.signal);
+    if (!approved)
+        throw new CliError('tool_data_consent_required', 'No new data operation was submitted. Use --approve-tool-change for explicit automation consent.', 2);
+    const key = identifier(options.request ?? randomUUID());
+    const readCommand = `tools ${action === 'checkpoint' ? 'checkpoint-status' : 'transition'} ${instance} ${key}`;
+    output('tool_data_intent', { instance_id: instance, request_key: key, action }, `Request: ${key}\nIf interrupted, use ${readCommand}. Do not create a replacement request.`);
+    if (action === 'checkpoint') {
+        const value = await api(`${path}/capture-requests`, { ...auth, method: 'POST', idempotencyKey: key, body: { save_data_consent: true } });
+        toolStateRead(value, await toolCaptureAccepted(value, selected, { key }));
+        print(await reads.capture(key, { id: value.id, digest: value.request_digest }), output);
+    }
+    else {
+        const setup = await lifecycle.instances(), duration = options.seconds === undefined ? setup.setup.default_duration_seconds : Number(options.seconds);
+        if (!Number.isSafeInteger(duration) || duration < 60 || duration > setup.setup.maximum_duration_seconds)
+            throw new CliError('tool_duration_invalid', 'Choose a supported --seconds duration before starting a successor.', 2);
+        const usageQuote = await allocationApproval(scope, options, { implementation_id: details.implementation_id, release_id: null,
+            dataset_id: null, duration_seconds: duration, launch_request_key: key,
+            restore: { instance_id: instance, checkpoint_id: checkpoint ?? null, action: action } }, output);
+        const input = { action: action, checkpoint_id: checkpoint ?? null, duration_seconds: duration, usage_quote_id: usageQuote };
+        const value = await api(`${path}/transitions`, { ...auth, method: 'POST', idempotencyKey: key, body: { ...input, restore_consent: true } });
+        toolStateRead(value, await toolTransitionAccepted(value, selected, { key, input }));
+        print(await reads.transition(key, { id: value.id, digest: value.request_digest, input }), output);
+    }
+}

package/dist/cli/src/tool-datasets.js

@@ -0,0 +1,176 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+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 { exportDataset } from './dataset-export.js';
+import { toolLifecycleReads } from './tool-lifecycle-reads.js';
+import { toolStateReads } from './tool-state-reads.js';
+import { datasetReads } from './dataset-reads.js';
+import { datasetRead, datasetMatches, datasetEdits } from './dataset-contracts.js';
+const actions = new Set(['datasets', 'dataset', 'dataset-document', 'dataset-export', 'dataset-request', 'dataset-save', 'dataset-withdraw']);
+const interactive = (options) => !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+const text = (row) => `${row.id}  ${terminalText(row.name)} · version ${row.version} · ${row.state}\n${row.edit_count} saved edits`
+    + (row.problem ? '\n' + terminalText(row.problem) : '') + '\nSaved edits do not change a running tool.';
+async function question(title, signal) {
+    const prompt = createInterface({ input: process.stdin, output: process.stderr, terminal: false });
+    try {
+        return (await prompt.question(title, { signal })).trim();
+    }
+    finally {
+        prompt.close();
+    }
+}
+async function choose(path, title, describe, auth, signal, read) {
+    let page = 1;
+    while (true) {
+        const result = read ? await read(page) : await api(`${path}?page=${page}`, auth);
+        const rows = result.results.flatMap(row => { const label = describe(row); return label === null ? [] : [{ value: row.id, label }]; });
+        const value = await selectOne(title, [...rows,
+            ...(result.next ? [{ value: '__next__', label: 'Next page' }] : []),
+            ...(page > 1 ? [{ value: '__previous__', label: 'Previous page' }] : []), { value: '__cancel__', label: 'Cancel' }], signal);
+        if (value === '__cancel__')
+            throw new CliError('canceled', 'Dataset selection canceled. No changes were submitted.', 130);
+        if (value === '__next__')
+            page++;
+        else if (value === '__previous__')
+            page--;
+        else
+            return identifier(value);
+    }
+}
+export async function datasetRecipeFile(path, maximum, signal) {
+    if (!path.toLowerCase().endsWith('.json') || /[\u0000-\u001f\u007f]/.test(path))
+        throw new CliError('tool_dataset_file_invalid', 'Choose a regular JSON file.', 2);
+    let file;
+    try {
+        const before = await lstat(resolve(path));
+        if (!before.isFile() || before.isSymbolicLink() || !Number.isSafeInteger(before.size) || before.size < 1 || before.size > maximum)
+            throw new Error();
+        file = await open(resolve(path), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const held = await file.stat();
+        if (!held.isFile() || held.ino !== before.ino || held.dev !== before.dev || held.size !== before.size || held.mtimeMs !== before.mtimeMs)
+            throw new Error();
+        const parts = [];
+        let size = 0;
+        for await (const part of file.createReadStream({ autoClose: false })) {
+            signal.throwIfAborted();
+            size += part.length;
+            if (size > maximum)
+                throw new Error();
+            parts.push(part);
+        }
+        const after = await file.stat();
+        if (after.size !== held.size || size !== held.size || after.mtimeMs !== held.mtimeMs || after.ctimeMs !== held.ctimeMs)
+            throw new Error();
+        return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(parts)));
+    }
+    catch {
+        if (signal.aborted)
+            throw new CliError('canceled', 'Dataset read canceled. No edits were submitted.', 130);
+        throw new CliError('tool_dataset_file_invalid', 'Choose an unchanged regular JSON file within dataset transport capacity. No edits were submitted.', 2);
+    }
+    finally {
+        await file?.close();
+    }
+}
+export async function toolDatasetCommand(args, options, output) {
+    const action = args[0], save = action === 'dataset-save', withdraw = action === 'dataset-withdraw', write = save || withdraw;
+    if (!actions.has(action) || args.length > (save ? 3 : 2) || options.upload || options.service !== undefined || options.seconds !== undefined
+        || !save && (options.file !== undefined || options.request !== undefined) || !write && options.change
+        || action !== 'dataset-export' && (options.into !== undefined || options.approveDownload !== undefined)
+        || action !== 'datasets' && (options.page !== undefined || options.search !== undefined)
+        || options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page) || (options.search?.length ?? 0) > 200) {
+        throw new CliError('arguments_invalid', 'Use tools datasets [checkpoint], dataset|dataset-document <version>, dataset-export [version] --into <file.json>, dataset-request <request>, dataset-save [checkpoint] [name] --file <edits.json>, or dataset-withdraw <version>.', 2);
+    }
+    const tty = interactive(options), scope = await selectedWorkspace({ ...options, interactive: tty });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const prefix = `/api/workspaces/${scope.workspace}/tools`;
+    const reads = datasetReads(prefix, scope, options.signal), selectedScope = { workspace: scope.workspace, actor: scope.owner, kind: 'tool' };
+    if (action === 'dataset-export')
+        return exportDataset(prefix, args[1], scope, options, output);
+    if (action === 'datasets') {
+        const result = await reads.page({ page: Number(options.page ?? 1), query: options.search, source: args[1] ? identifier(args[1]) : undefined });
+        output('tool_datasets', result, (result.results.map(text).join('\n\n') || 'No matching tool datasets.')
+            + `\nPage ${result.page}, ${result.count} matching datasets.${result.next ? ` Use --page ${result.page + 1} with the same checkpoint and search to continue.` : ''}`);
+        return;
+    }
+    if (['dataset', 'dataset-document', 'dataset-request'].includes(action)) {
+        const key = identifier(args[1] ?? ''), document = action === 'dataset-document';
+        const row = action === 'dataset-request' ? await reads.original(key) : await reads.detail(key);
+        if (document) {
+            const value = await reads.document(row);
+            output('tool_dataset_document', value, JSON.stringify(value, null, 2));
+        }
+        else
+            output('tool_dataset', row, text(row));
+        return;
+    }
+    if (withdraw) {
+        const key = identifier(args[1] ?? ''), row = await reads.detail(key);
+        const approved = options.change || tty && await selectOne(`Withdraw ${terminalText(row.name)} version ${row.version}? Other versions and running tools stay unchanged.`, [{ value: false, label: 'Cancel' }, { value: true, label: 'Withdraw version' }], options.signal);
+        if (!approved)
+            throw new CliError('tool_dataset_consent_required', 'Use --approve-tool-change to withdraw this exact version. No change was submitted.', 2);
+        const result = await api(`${prefix}/datasets/${key}`, { ...auth, method: 'DELETE' });
+        datasetRead(result, datasetMatches(result, selectedScope, { id: key, digest: row.request_digest, withdrawn: true }));
+        output('tool_dataset', result, text(result));
+        return;
+    }
+    let checkpoint = args[1];
+    if (!checkpoint && tty) {
+        const instance = await choose(`${prefix}/instances`, 'Tool instance', row => `${terminalText(row.name)} ${terminalText(row.version)}`, auth, options.signal, page => toolLifecycleReads(scope, options.signal).instances(page));
+        checkpoint = await choose(`${prefix}/instances/${instance}/checkpoints`, 'Saved tool data', row => row.records.available ? `${row.kind} · ${row.captured_at}` : null, auth, options.signal, page => toolStateReads(scope, instance, options.signal).checkpoints(page));
+    }
+    if (!checkpoint)
+        throw new CliError('tool_checkpoint_required', 'Provide a checkpoint with record pages from tools checkpoints.', 2);
+    checkpoint = identifier(checkpoint);
+    const name = args[2] ?? (tty ? await question('Dataset name: ', options.signal) : '');
+    if (!name || name !== name.trim() || name.length > 120 || /[\u0000-\u001f\u007f-\u009f]/.test(name))
+        throw new CliError('tool_dataset_name_required', 'Provide a dataset name of up to 120 characters.', 2);
+    const path = options.file ?? (tty ? await question('Dataset edits JSON path: ', options.signal) : '');
+    if (!path)
+        throw new CliError('tool_dataset_file_required', 'Provide --file <edits.json>. No file was read or uploaded.', 2);
+    const catalog = await reads.page({ source: checkpoint });
+    const maximum = catalog.capacity?.recipe_bytes;
+    if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 8 * 1024 * 1024)
+        throw new CliError('tool_dataset_capacity_invalid', 'Dataset transport capacity is unavailable. No file was read.', 2);
+    const input = await datasetRecipeFile(path, maximum, options.signal);
+    let edits = input, previous = null;
+    if (input && typeof input === 'object' && !Array.isArray(input)) {
+        const value = input;
+        if (value.schema === 'firedrill.tool-dataset.v1') {
+            if (value.checkpoint_id !== checkpoint)
+                throw new CliError('tool_dataset_base_invalid', 'This export belongs to a different checkpoint. No edits were submitted.', 2);
+            edits = value.edits;
+        }
+        else if (Object.keys(value).every(key => ['edits', 'previous_version_id'].includes(key)) && Array.isArray(value.edits)) {
+            edits = value.edits;
+            if (value.previous_version_id !== null && value.previous_version_id !== undefined)
+                previous = identifier(String(value.previous_version_id));
+        }
+        else
+            throw new CliError('tool_dataset_file_invalid', 'Use an edit array, an exported dataset or edits with an optional previous_version_id.', 2);
+    }
+    if (!datasetEdits(edits))
+        throw new CliError('tool_dataset_file_invalid', 'Use a typed edit array. Keep exact integer and decimal values as strings; unsafe numeric values are not rewritten.', 2);
+    const body = { checkpoint_id: checkpoint, previous_version_id: previous, name, edits, save_consent: true };
+    if (Buffer.byteLength(JSON.stringify(body)) > maximum)
+        throw new CliError('tool_dataset_capacity', 'These edits exceed dataset transport capacity.', 2);
+    const approved = options.change || tty && await selectOne(`Save ${edits.length} synthetic-data edits as a private version? This will not change a running tool.`, [{ value: false, label: 'Cancel' }, { value: true, label: 'Save dataset' }], options.signal);
+    if (!approved)
+        throw new CliError('tool_dataset_consent_required', 'Use --approve-tool-change to save the selected edits. No edits were submitted.', 2);
+    const key = identifier(options.request ?? randomUUID());
+    output('tool_dataset_intent', { request_key: key, checkpoint_id: checkpoint, name }, `Request: ${key}\nIf interrupted, use tools dataset-request ${key}. Keep the original file and request ID; do not submit a replacement.`);
+    const row = await api(`${prefix}/datasets`, { ...auth, method: 'POST', body, idempotencyKey: key });
+    const selection = { key, source: checkpoint, previous, name, editCount: edits.length };
+    datasetRead(row, datasetMatches(row, selectedScope, selection));
+    const recorded = await reads.original(key, { ...selection, id: row.id, digest: row.request_digest });
+    output('tool_dataset', recorded, text(recorded));
+    if (['failed', 'withdrawn'].includes(recorded.state))
+        throw new CliError('tool_dataset_not_saved', recorded.problem ?? 'The original dataset save did not complete.', 2);
+}

package/dist/cli/src/tool-group-contracts.js

@@ -0,0 +1 @@
+export * from '../../contracts/tool-group-contracts.js';

package/dist/cli/src/tool-group-reads.js

@@ -0,0 +1,26 @@
+import { api } from './auth.js';
+import { identifier } from './world-contracts.js';
+import { toolGroupRead, toolGroupsMatch, toolGroupMatches, toolGroupAccepted, toolGroupMembersMatch } from './tool-group-contracts.js';
+export function toolGroupReads(owner, signal) {
+    const scope = { workspace: owner.workspace, actor: owner.owner }, auth = { actor: owner.owner, workspace: owner.workspace, signal };
+    const prefix = `/api/workspaces/${scope.workspace}/tools`;
+    return {
+        async page(page = 1, query = '') {
+            const value = await api(`${prefix}/setups?page=${page}&q=${encodeURIComponent(query)}`, auth);
+            return toolGroupRead(value, toolGroupsMatch(value, scope, query, page));
+        },
+        async detail(id, selected = {}) {
+            const value = await api(`${prefix}/setups/${identifier(id)}`, auth);
+            return toolGroupRead(value, toolGroupMatches(value, scope, { ...selected, id }));
+        },
+        async original(key, selected = {}) {
+            const value = await api(`${prefix}/setup-requests/${identifier(key)}`, auth);
+            return toolGroupRead(value, selected.input ? await toolGroupAccepted(value, scope, key, selected.input, selected)
+                : toolGroupMatches(value, scope, { ...selected, key }));
+        },
+        async members(group, page = 1, query = '') {
+            const value = await api(`${prefix}/setups/${identifier(group)}/members?page=${page}&q=${encodeURIComponent(query)}`, auth);
+            return toolGroupRead(value, toolGroupMembersMatch(value, scope, group, query, page));
+        },
+    };
+}

package/dist/cli/src/tool-group-state.js

@@ -0,0 +1,147 @@
+import { randomUUID } from 'node:crypto';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { selectedWorkspace } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { requestInput } from './request-input.js';
+import { groupStateMatches, groupStateInputsEqual, groupStatePageMatches, groupStateMemberPageMatches, groupStateQuoteMatches } from '../../contracts/tool-group-state-contracts.js';
+import { allocationCredits } from '../../contracts/tool-runtime-billing-contracts.js';
+const interactive = (options) => !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+const actions = ['group-state', 'group-state-members', 'group-state-status', 'group-state-quote', 'capture-group', 'reset-group', 'fork-group'];
+const text = (one) => `${terminalText(one.name)}: ${terminalText(one.state)}\nOperation: ${one.id}\nRequest: ${one.request_key}`
+    + `\n${one.counts.saved}/${one.counts.total} saved · ${one.counts.released}/${one.counts.total} resumed · ${one.counts.ready}/${one.counts.total} replacements ready`
+    + (one.problem ? '\n' + terminalText(one.problem) : '');
+function input(value, action) {
+    const row = value;
+    if (!row || typeof row !== 'object' || Array.isArray(row)
+        || Object.keys(row).sort().join(',') !== 'action,duration_seconds,member_quotes,name,source_operation_id,state_consent'
+        || row.action !== action || typeof row.name !== 'string' || !row.name.trim() || row.name !== row.name.trim() || row.name.length > 120
+        || /[\u0000-\u001f\u007f]/.test(row.name) || row.state_consent !== true || !Array.isArray(row.member_quotes)
+        || (action === 'capture' ? row.duration_seconds !== null || row.source_operation_id !== null || row.member_quotes.length !== 0
+            : !Number.isSafeInteger(row.duration_seconds) || row.duration_seconds < 60 || typeof row.source_operation_id !== 'string'
+                || !row.member_quotes.length || row.member_quotes.some(one => !one || typeof one !== 'object'
+                || Object.keys(one).sort().join(',') !== 'position,usage_quote_id' || !Number.isSafeInteger(one.position) || one.position < 0
+                || typeof one.usage_quote_id !== 'string') || new Set(row.member_quotes.map(one => one.position)).size !== row.member_quotes.length)) {
+        throw new CliError('tool_group_state_input_invalid', 'Provide the complete group-state request with explicit consent and one reviewed runtime quote per replacement.', 2);
+    }
+    if (row.source_operation_id)
+        identifier(row.source_operation_id);
+    for (const one of row.member_quotes)
+        identifier(one.usage_quote_id);
+    return row;
+}
+export async function toolGroupStateCommand(args, options, output) {
+    const action = args[0], paged = ['group-state', 'group-state-members'].includes(action), changing = ['capture-group', 'reset-group', 'fork-group'].includes(action);
+    if (!actions.includes(action) || args.length !== (['group-state-members', 'group-state-status'].includes(action) ? 3 : 2)
+        || options.service !== undefined || options.upload || options.usageQuote !== undefined
+        || options.page !== undefined && !paged || options.search !== undefined && !paged
+        || options.file !== undefined && !changing && action !== 'group-state-quote'
+        || options.seconds !== undefined && !['reset-group', 'fork-group'].includes(action)
+        || options.request !== undefined && !changing && action !== 'group-state-quote' || options.change && !changing
+        || options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page) || (options.search?.length ?? 0) > 200) {
+        throw new CliError('arguments_invalid', 'Use tools group-state <setup>, group-state-members|group-state-status <setup> <operation>, capture-group <setup>, or group-state-quote|reset-group|fork-group <setup> [--file request.json].', 2);
+    }
+    const scope = await selectedWorkspace({ ...options, interactive: interactive(options) });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal }, group = identifier(args[1]);
+    const base = `/api/workspaces/${scope.workspace}/tools/setups/${group}`;
+    const detail = async (id, own = false) => {
+        const value = await api(`${base}/state-operations/${identifier(id)}`, auth);
+        if (!groupStateMatches(value, scope.workspace, group, own ? scope.owner : undefined, own ? id : undefined))
+            throw new CliError('tool_group_state_response_invalid', 'The retained operation did not match its original setup.', 2);
+        return value;
+    };
+    const listing = async (page, search = '', capture = false) => {
+        const result = await api(`${base}/state-operations?page=${page}&q=${encodeURIComponent(search)}${capture ? '&action=capture' : ''}`, auth);
+        if (!groupStatePageMatches(result, scope.workspace, group, page) || !result.runtime
+            || !Number.isSafeInteger(result.runtime.default_seconds) || !Number.isSafeInteger(result.runtime.maximum_seconds)
+            || result.runtime.default_seconds < 60 || result.runtime.maximum_seconds < result.runtime.default_seconds)
+            throw new CliError('tool_group_state_response_invalid', 'The group-state page is unavailable. No change was requested.', 2);
+        return result;
+    };
+    const continuation = (value, command) => `\nPage ${value.page}; ${value.count} matching items.`
+        + (value.next ? `\nNext: firedrill tools ${command} --workspace ${scope.workspace} --page ${value.page + 1}`
+            + (options.search ? ` --search '${terminalText(options.search).replaceAll("'", "'\\''")}'` : '') : '');
+    if (action === 'group-state') {
+        const value = await listing(Number(options.page ?? 1), options.search ?? '');
+        output('tool_group_state_history', value, (value.results.map(text).join('\n\n') || 'No coordinated group state saved.') + continuation(value, `${action} ${group}`));
+        return;
+    }
+    if (action === 'group-state-status') {
+        const value = await detail(args[2]);
+        output('tool_group_state', value, text(value));
+        return;
+    }
+    if (action === 'group-state-members') {
+        const original = await detail(args[2]), page = Number(options.page ?? 1);
+        const value = await api(`${base}/state-operations/${original.id}/members?page=${page}&q=${encodeURIComponent(options.search ?? '')}`, auth);
+        if (!groupStateMemberPageMatches(value, page))
+            throw new CliError('tool_group_state_response_invalid', 'This member page could not be read.', 2);
+        output('tool_group_state_members', value, (value.results.map(one => `${terminalText(one.name)}: ${terminalText(one.state)}\nInstance: ${one.instance_id}`
+            + (one.event_watermark !== null ? `\nLast completed request: ${one.event_watermark}` : '') + (one.successor_id ? `\nReplacement: ${one.successor_id}` : '')
+            + (one.captured_at ? `\nSaved: ${one.captured_at}` : '')).join('\n\n') || 'No matching members.') + continuation(value, `${action} ${group} ${original.id}`));
+        return;
+    }
+    const key = identifier(options.request ?? randomUUID()), kind = action === 'capture-group' ? 'capture' : action === 'fork-group' ? 'fork' : 'reset';
+    let selected;
+    if (options.file && action !== 'group-state-quote')
+        selected = input(JSON.parse(await requestInput(options.file, options.signal)), kind);
+    else if (action === 'capture-group')
+        selected = { action: 'capture', name: 'Group checkpoint', source_operation_id: null, duration_seconds: null, member_quotes: [], state_consent: true };
+    else {
+        let quoteInput;
+        if (action === 'group-state-quote') {
+            if (!options.file)
+                throw new CliError('tool_group_state_input_required', 'Provide --file with action, source_operation_id and duration_seconds; keep --request-key for the eventual replacement.', 2);
+            const row = JSON.parse(await requestInput(options.file, options.signal));
+            if (!row || Object.keys(row).sort().join(',') !== 'action,duration_seconds,source_operation_id' || !['reset', 'fork'].includes(row.action)
+                || !Number.isSafeInteger(row.duration_seconds) || row.duration_seconds < 60)
+                throw new CliError('tool_group_state_input_invalid', 'Choose a reset or fork, a completed group checkpoint and finite runtime.', 2);
+            quoteInput = { ...row, source_operation_id: identifier(row.source_operation_id), operation_request_key: key };
+        }
+        else {
+            if (!interactive(options))
+                throw new CliError('tool_group_state_input_required', 'Review group-state-quote first, then provide its request as --file with the same --request-key and --approve-tool-change.', 2);
+            let checkpoint, page = 1, defaults;
+            while (!checkpoint) {
+                const result = await listing(page, '', true);
+                defaults = result.runtime;
+                const choice = await selectOne('Saved group checkpoint', [...result.results.filter(one => one.coordinated).map(one => ({ value: one.id, label: one.name, detail: `${one.counts.total} tools · ${one.created_at}` })),
+                    ...(result.next ? [{ value: 'next', label: 'Next page' }] : []), ...(page > 1 ? [{ value: 'previous', label: 'Previous page' }] : []), { value: 'cancel', label: 'Cancel' }], options.signal);
+                if (choice === 'cancel')
+                    throw new CliError('canceled', 'Nothing changed.', 130);
+                if (choice === 'next')
+                    page++;
+                else if (choice === 'previous')
+                    page--;
+                else
+                    checkpoint = result.results.find(one => one.id === choice);
+            }
+            const seconds = options.seconds === undefined ? await selectOne('Replacement runtime', [...new Set([defaults.default_seconds, 3600, 86400, 604800])]
+                .filter(one => one <= defaults.maximum_seconds).sort((a, b) => a - b).map(one => ({ value: one, label: `${one / 3600} hours` })), options.signal) : Number(options.seconds);
+            quoteInput = { action: kind, source_operation_id: checkpoint.id, duration_seconds: seconds, operation_request_key: key };
+        }
+        const quoted = await api(`${base}/state-quotes`, { ...auth, method: 'POST', idempotencyKey: randomUUID(), body: quoteInput });
+        if (!groupStateQuoteMatches(quoted, scope.workspace, group, key, quoteInput))
+            throw new CliError('billing_scope_mismatch', 'Review current runtime quotes for this entire group.', 2);
+        selected = { action: quoteInput.action, name: quoteInput.action === 'fork' ? 'Group fork' : 'Group reset', source_operation_id: quoted.source_operation_id,
+            duration_seconds: quoted.duration_seconds, member_quotes: quoted.members.map(one => ({ position: one.position, usage_quote_id: one.quote.id })), state_consent: true };
+        output('tool_group_state_quote', { ...quoted, request: selected }, quoted.members.map(one => `${terminalText(one.name)}: ${allocationCredits(one.quote)} credits maximum`).join('\n')
+            + `\nKeep request ${key}. Only supported native data is restored; process memory and real-account state are not included.`);
+        if (action === 'group-state-quote')
+            return;
+    }
+    const approved = options.change || interactive(options) && await selectOne(selected.action === 'fork'
+        ? 'Approve every runtime budget and start an isolated set from the saved checkpoint? Original instances stay unchanged.'
+        : 'Pause all source services for this group? An uncertain outcome closes the controlled instances instead of resuming them.', [{ value: false, label: 'Cancel' }, { value: true, label: selected.action === 'capture' ? 'Save group checkpoint' : 'Approve group replacement' }], options.signal);
+    if (!approved)
+        throw new CliError('tool_group_state_consent_required', 'Nothing changed. Use --approve-tool-change only for the selected request and budgets.', 2);
+    output('tool_group_state_intent', { group_id: group, request_key: key, request: selected }, `Request: ${key}\nRecovery: firedrill tools group-state-status ${group} ${key} --workspace ${scope.workspace}\nDo not replace an uncertain request.`);
+    const value = await api(`${base}/state-operations`, { ...auth, method: 'POST', idempotencyKey: key, body: selected });
+    if (!groupStateMatches(value, scope.workspace, group, scope.owner, key) || !groupStateInputsEqual(value.request, selected))
+        throw new CliError('tool_group_state_acceptance_unconfirmed', 'Inspect the original request. Nothing was repeated.', 2);
+    const retained = await detail(key, true);
+    if (!groupStateInputsEqual(retained.request, selected))
+        throw new CliError('tool_group_state_acceptance_unconfirmed', 'Inspect the exact original request. Nothing was repeated.', 2);
+    output('tool_group_state', retained, text(retained));
+}