firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/target-models.js

@@ -0,0 +1,109 @@
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { selectedWorkspace, selectedWorld } from './world-access.js';
+import { approval, auth, choosePaged, interactive, line, query } from './configuration.js';
+import { inputSchema, readMetadata, remember, requestAction, retained, validateBody } from './configuration-intents.js';
+async function current(context, options, id) {
+    const data = await api(context.prefix + '/model-connections?' + query(options)
+        + (id ? '&connection_id=' + identifier(id) : ''), auth(context, options));
+    if (!Number.isSafeInteger(data.configuration_revision) || data.configuration_revision < 0 || !Array.isArray(data.providers)
+        || data.providers.some(one => !['anthropic', 'openai'].includes(one.id))) {
+        throw new CliError('model_configuration_unavailable', 'Model connection metadata could not be confirmed.', 2);
+    }
+    return data;
+}
+export async function targetModelsCommand(args, options, output) {
+    const interactiveMode = interactive(options);
+    let action = args[0] ?? 'list';
+    if (!['list', 'show', 'save', 'remove', 'schema', 'status', 'resume', 'withdraw', 'forget'].includes(action) || args.length > 2) {
+        throw new CliError('arguments_invalid', 'Use firedrill models list|show|save|remove|schema or status|resume|withdraw|forget --request-key <id>.', 2);
+    }
+    if (action === 'schema') {
+        if (args[1] && args[1] !== 'remove' || options.file || options.request || options.approve)
+            throw new CliError('arguments_invalid', 'Use models schema [remove] --json.', 2);
+        output('result', inputSchema(args[1] === 'remove' ? 'model_remove' : 'model'), 'Use --json for the exact model connection metadata fields. Credentials belong in Vault.');
+        return;
+    }
+    if (['status', 'resume', 'withdraw', 'forget'].includes(action)) {
+        if (args.length > 1 || options.file || ['status', 'resume'].includes(action) && options.approve || !options.request)
+            throw new CliError('arguments_invalid', 'Use --request-key <id> to recover the same model connection request.', 2);
+        const scope = await selectedWorkspace({ ...options, interactive: interactiveMode });
+        const intent = await retained(scope, identifier(options.request));
+        if (!['model', 'model_remove'].includes(intent.kind) || options.world && options.world !== intent.world) {
+            throw new CliError('model_request_mismatch', 'This recovery record belongs to another action or world.', 2);
+        }
+        const context = await selectedWorld({ ...options, interactive: false, world: intent.world, expectedOwner: scope.owner });
+        if (action === 'withdraw' || action === 'forget')
+            await approval(options, action === 'withdraw'
+                ? 'Withdraw this exact model access request? An accepted change will not be undone.'
+                : 'Remove only this private recovery copy? A delayed or accepted cloud request is unchanged.');
+        return requestAction(context, intent, action, options.signal, output);
+    }
+    if ((options.file || options.approve || options.request) && !['save', 'remove'].includes(action)) {
+        throw new CliError('arguments_invalid', 'Use a metadata file or approval only when saving or removing a connection.', 2);
+    }
+    const context = await selectedWorld({ ...options, interactive: interactiveMode });
+    if (!args.length && interactiveMode)
+        action = await selectOne('Model access', [
+            { value: 'list', label: 'View model connections' }, { value: 'save', label: 'Connect a saved runtime credential' },
+            { value: 'remove', label: 'Remove a connection' }
+        ], options.signal);
+    if (action === 'list') {
+        if (args[1])
+            throw new CliError('arguments_invalid', 'Use models show <connection> to read one connection.', 2);
+        const data = await current(context, options);
+        output('result', data, [`Configuration revision ${data.configuration_revision}`, ...data.results.map(one => `${one.id}  ${one.key_variable} · ${one.provider}\n  ${one.models.join(', ')}${one.mapping_current ? '' : '\n  Saved mapping changed. Review this connection.'}`),
+            ...(!data.count ? ['No model connections. Save a runtime secret in Configuration, then use firedrill models save.'] : []),
+            ...(data.next ? [`Next page: --page ${data.page + 1}`] : [])].join('\n'));
+        return;
+    }
+    let selected = null;
+    if (action === 'show' || action === 'remove') {
+        if (args[1]) {
+            const data = await current(context, { ...options, search: '', page: '1' }, args[1]);
+            selected = data.results.find(one => one.id === identifier(args[1])) ?? null;
+        }
+        else if (interactiveMode)
+            selected = await choosePaged('Model connection', context.prefix + '/model-connections', context, options, one => ({ label: one.key_variable, detail: `${one.provider} · ${one.models.join(', ')}` }));
+        if (!selected)
+            throw new CliError('model_connection_required', 'Choose a connection ID from firedrill models.', 2);
+        if (action === 'show') {
+            output('result', selected, `${selected.key_variable} · ${selected.provider}\nEndpoint variable: ${selected.base_url_variable}\nAllowed models: ${selected.models.join(', ')}\nMapping: ${selected.mapping_current ? 'Current' : 'Changed; review required'}`);
+            return;
+        }
+    }
+    else if (args[1])
+        throw new CliError('arguments_invalid', 'Use models save to select a runtime credential, or --file <metadata.json>.', 2);
+    const kind = action === 'save' ? 'model' : 'model_remove';
+    let body;
+    if (options.file)
+        body = await readMetadata(options.file);
+    else {
+        if (!interactiveMode)
+            throw new CliError('model_input_required', 'Run models save in a terminal, or provide --file <metadata.json> --approve-configuration. Use models schema --json for fields.', 2);
+        const data = await current(context, { ...options, search: '', page: '1' }, selected?.id);
+        if (action === 'remove') {
+            if (!data.results.some(one => one.id === selected.id && one.revision === selected.revision)) {
+                throw new CliError('configuration_conflict', 'The model connection changed. Review it before removing access.', 2);
+            }
+            body = { configuration_revision: data.configuration_revision };
+            output('model_review', { connection_id: selected.id, key_variable: selected.key_variable }, `Remove ${selected.key_variable} scoped model access. This does not delete its Vault credential or change the provider account.`);
+        }
+        else {
+            const mapping = await choosePaged('Runtime credential mapping', context.prefix + '/model-connection-mappings', context, options, one => ({ label: one.name, detail: one.phase }));
+            if (!mapping)
+                throw new CliError('model_mapping_required', 'Save a runtime secret in Configuration first.', 2);
+            const provider = await selectOne('Model provider', data.providers.map(one => ({ value: one, label: one.name })), options.signal);
+            const base = await line('Original endpoint variable', 128, options.signal, provider.base_url_variable);
+            const names = (await line('Exact model names, separated by commas (not an API key)', 128999, options.signal)).split(',').map(one => one.trim());
+            body = { configuration_revision: data.configuration_revision, mapping_id: mapping.id, provider: provider.id,
+                base_url_variable: base, models: names, authorize_target_model_usage: true };
+            output('model_review', { mapping_id: mapping.id, variable: mapping.name, provider: provider.id, models: names, base_url_variable: base }, `${mapping.name} · ${provider.name}\nEndpoint variable: ${base}\nAllowed models: ${names.join(', ')}\nOnly this agent's approved model calls use the account. No model call is started by saving.`);
+        }
+    }
+    validateBody(kind, body);
+    await approval(options, 'Save this model access change and its private metadata recovery copy?');
+    return remember(context, kind, selected?.id ?? null, body, options.request, options.signal, output);
+}

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

@@ -0,0 +1,224 @@
+import { randomUUID } from 'node:crypto';
+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 { allocationApproval } from './tool-runtime.js';
+import { catalogRead, catalogPageMatches, catalogReleaseDetailMatches, catalogServicesMatch, catalogServiceMatches, catalogOperationsMatch, catalogOperationMatches, catalogSetupMatches, catalogSetupsMatch } from './catalog-contracts.js';
+const tty = (options) => !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+const text = (row) => `${terminalText(row.name)} ${terminalText(row.version)}: ${terminalText(row.state)}\nRequest: ${row.request_key}`
+    + (row.instance_id ? `\nInstance: ${row.instance_id}\nUse tools instance ${row.instance_id} to inspect actual startup.` : '')
+    + (row.implementation_id ? `\nSaved version: ${row.implementation_id}` : '') + (row.problem ? `\n${terminalText(row.problem)}` : '');
+async function chooseItem(read, prompt, item, options) {
+    let current = 1;
+    while (true) {
+        const page = await read(current);
+        const choices = page.results.map(row => {
+            const value = item(row);
+            return { value: { kind: 'item', key: value.key }, label: value.label, detail: value.detail };
+        });
+        if (current > 1)
+            choices.push({ value: { kind: 'previous' }, label: 'Previous page', detail: '' });
+        if (page.next)
+            choices.push({ value: { kind: 'next' }, label: 'Next page', detail: '' });
+        if (!choices.length)
+            throw new CliError('catalog_selection_empty', 'No matching item is available. Review the catalog version.');
+        choices.push({ value: { kind: 'cancel' }, label: 'Cancel', detail: '' });
+        const selected = await selectOne(prompt, choices, options.signal);
+        if (selected.kind === 'cancel')
+            throw new CliError('canceled', 'Catalog selection canceled.', 2);
+        if (selected.kind === 'item')
+            return selected.key;
+        current += selected.kind === 'next' ? 1 : -1;
+    }
+}
+export async function toolCatalogCommand(args, options, output) {
+    const action = args[0], paged = ['catalog', 'catalog-categories', 'catalog-show', 'catalog-operations', 'catalog-setups'].includes(action);
+    const changing = ['add', 'save', 'catalog-withdraw'].includes(action);
+    if (!['catalog', 'catalog-categories', 'catalog-show', 'catalog-operations', 'catalog-operation', 'catalog-setups', 'catalog-status', 'catalog-withdraw', 'add', 'save'].includes(action)
+        || args.length > (action === 'catalog-operation' ? 4 : 2) || action === 'catalog' && args.length > 1
+        || action === 'catalog-categories' && args.length > 1 || options.category !== undefined && action !== 'catalog'
+        || options.category !== undefined && !/^[a-z][a-z0-9-]{0,63}$/.test(options.category)
+        || !paged && (options.page !== undefined || options.search !== undefined)
+        || options.search !== undefined && action === 'catalog-setups'
+        || !['add', 'save'].includes(action) && options.request !== undefined
+        || action !== 'add' && options.seconds !== undefined || options.upload || options.file !== undefined
+        || options.usageQuote !== undefined && action !== 'add'
+        || !['catalog-operations'].includes(action) && options.service !== undefined || !changing && options.change
+        || options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page) || (options.search?.length ?? 0) > 200) {
+        throw new CliError('arguments_invalid', 'Use tools catalog, catalog-show [release], catalog-operations <release> --service <key>, catalog-operation <release> <service> <operation>, add|save [release], catalog-setups [release], catalog-status <request>, or catalog-withdraw <request>.', 2);
+    }
+    const scope = await selectedWorkspace({ ...options, interactive: tty(options) });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal }, prefix = `/api/workspaces/${scope.workspace}/tools`;
+    const owner = { actor: scope.owner, workspace: scope.workspace };
+    const readCatalog = async (page, search = '') => {
+        const value = await api(`${prefix}/library?page=${page}&q=${encodeURIComponent(search)}&category=${encodeURIComponent(options.category ?? '')}`, auth);
+        return catalogRead(value, catalogPageMatches(value, scope.workspace, search, page, options.category ?? ''));
+    };
+    const readSetup = async (key, selected) => {
+        const value = await api(`${prefix}/catalog-requests/${key}`, auth);
+        return catalogRead(value, catalogSetupMatches(value, owner, { key, ...selected }));
+    };
+    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))}` : ''}${options.category ? ` --category ${quote(options.category)}` : ''}` : ''}`;
+    if (action === 'catalog-categories') {
+        const pageNumber = Number(options.page ?? 1), query = options.search ?? '';
+        const page = await api(`${prefix}/library/categories?page=${pageNumber}&q=${encodeURIComponent(query)}`, auth);
+        if (page.workspace_id !== scope.workspace || page.query !== query.trim() || page.page !== pageNumber || !Number.isSafeInteger(page.count) || page.count < 0
+            || !Number.isSafeInteger(page.page_size) || page.page_size < 1 || page.page_size > 100 || !Array.isArray(page.results) || page.results.length > page.page_size
+            || !page.results.every(row => !!row && /^[a-z][a-z0-9-]{0,63}$/.test(row.key) && typeof row.label === 'string' && row.label.length <= 64))
+            throw new CliError('catalog_categories_invalid', 'The catalog category response could not be confirmed.', 2);
+        output('tool_catalog_categories', page, (page.results.map(row => `${row.key}  ${terminalText(row.label)}`).join('\n') || 'No matching categories.')
+            + continuation(page, 'catalog-categories'));
+        return;
+    }
+    if (action === 'catalog') {
+        const page = await readCatalog(Number(options.page ?? 1), options.search ?? '');
+        output('tool_catalog', page, page.results.map(row => `${row.id}  ${terminalText(row.name)} ${terminalText(row.version)}\n${row.operation_count} operations · ${row.interfaces.join(', ')}${!row.available ? ' · unavailable' : ''}`)
+            .join('\n\n') + continuation(page, 'catalog'));
+        return;
+    }
+    if (action === 'catalog-setups') {
+        const release = args[1] ? identifier(args[1]) : null;
+        const page = await api(`${prefix}/catalog-setups?page=${options.page ?? '1'}${release ? `&release_id=${release}` : ''}`, auth);
+        catalogRead(page, catalogSetupsMatch(page, owner, release, Number(options.page ?? 1)));
+        output('catalog_setups', page, (page.results.map(text).join('\n\n') || 'No catalog setups requested by this account in the workspace.')
+            + continuation(page, `catalog-setups${release ? ` ${release}` : ''}`));
+        return;
+    }
+    if (action === 'catalog-status' || action === 'catalog-withdraw') {
+        const key = identifier(args[1] ?? ''), path = `${prefix}/catalog-requests/${key}`;
+        const original = await readSetup(key);
+        if (action === 'catalog-status') {
+            output('catalog_setup', original, text(original));
+            return;
+        }
+        let consent = options.change === true;
+        if (!consent && tty(options))
+            consent = await selectOne('Withdraw the original unfinished catalog setup?', [
+                { value: false, label: 'Keep the setup' }, { value: true, label: 'Withdraw it' }
+            ], options.signal);
+        if (!consent)
+            throw new CliError('catalog_withdraw_consent_required', 'Use --approve-tool-change to withdraw the original unfinished setup.', 2);
+        const row = await api(path, { ...auth, method: 'DELETE', body: { withdraw_consent: true } });
+        catalogRead(row, catalogSetupMatches(row, owner, { key, id: original.id }));
+        const observed = await readSetup(key, { id: original.id });
+        output('catalog_setup', observed, text(observed));
+        return;
+    }
+    let release = args[1];
+    if (!release && tty(options)) {
+        let page = 1;
+        while (!release) {
+            const results = await readCatalog(page);
+            const choices = results.results.filter(row => row.available && row.saved_version?.state !== 'revoked').map(row => ({ value: row.id,
+                label: `${row.name} ${row.version}`, detail: `${row.operation_count} operations · ${row.interfaces.join(', ')}` }));
+            if (page > 1)
+                choices.push({ value: '__previous__', label: 'Previous page', detail: '' });
+            if (results.next)
+                choices.push({ value: '__next__', label: 'Next page', detail: '' });
+            if (!choices.length)
+                throw new CliError('catalog_empty', 'No catalog tool is available. Import a supported package or inspect tools versions.');
+            choices.push({ value: '__cancel__', label: 'Cancel', detail: '' });
+            const selected = await selectOne('Choose a catalog tool', choices, options.signal);
+            if (selected === '__cancel__')
+                throw new CliError('canceled', 'Catalog selection canceled.', 2);
+            if (selected === '__next__')
+                page++;
+            else if (selected === '__previous__')
+                page--;
+            else
+                release = selected;
+        }
+    }
+    const releaseId = identifier(release ?? ''), base = `${prefix}/library/${releaseId}`;
+    const selected = await api(base, auth);
+    catalogRead(selected, catalogReleaseDetailMatches(selected, scope.workspace, releaseId));
+    const readServices = async (page, search = '') => {
+        const value = await api(`${base}/services?page=${page}&q=${encodeURIComponent(search)}`, auth);
+        return catalogRead(value, catalogServicesMatch(value, selected, search, page));
+    };
+    const readOperations = async (service, page, search = '') => {
+        const value = await api(`${base}/services/${service}/operations?page=${page}&q=${encodeURIComponent(search)}`, auth);
+        return catalogRead(value, catalogOperationsMatch(value, selected, service, search, page));
+    };
+    if (action === 'catalog-operations' || action === 'catalog-operation') {
+        let service = action === 'catalog-operations' ? options.service : args[2];
+        if (!service && tty(options))
+            service = await chooseItem(readServices, 'Choose a service', row => ({ key: row.key, label: terminalText(row.name), detail: `${row.operation_count} operations` }), options);
+        if (!service || !/^[a-z][a-z0-9_-]{0,79}$/.test(service))
+            throw new CliError('service_required', 'Choose a service from tools catalog-show.', 2);
+        const serviceValue = await api(`${base}/services/${service}`, auth);
+        catalogRead(serviceValue, catalogServiceMatches(serviceValue, selected, service));
+        if (action === 'catalog-operation') {
+            let name = args[3];
+            if (!name && tty(options))
+                name = await chooseItem(page => readOperations(service, page), 'Choose an operation', row => ({ key: row.name, label: terminalText(row.name), detail: `${row.transport.kind} · ${terminalText(row.effect)}` }), options);
+            if (!name || name.length > 200 || /[\u0000-\u001f\u007f]/.test(name))
+                throw new CliError('operation_required', 'Choose an operation from catalog-operations.', 2);
+            const row = await api(`${base}/services/${service}/operations/${encodeURIComponent(name)}`, auth);
+            catalogRead(row, catalogOperationMatches(row, selected, service, name));
+            output('catalog_operation', row, JSON.stringify(row, null, 2));
+            return;
+        }
+        const page = await readOperations(service, Number(options.page ?? 1), options.search ?? '');
+        output('catalog_operations', page, (page.results.map(row => `${terminalText(row.name)} · ${row.transport.kind} · ${terminalText(row.effect)}`
+            + (row.mcp_aliases?.length ? `\nMCP names: ${row.mcp_aliases.map(terminalText).join(', ')}` : '')).join('\n') || 'No matching operations.')
+            + continuation(page, `catalog-operations ${releaseId} --service ${service}`));
+        return;
+    }
+    if (action === 'catalog-show') {
+        const services = await readServices(Number(options.page ?? 1), options.search ?? '');
+        output('catalog_release', { ...selected, services }, `${terminalText(selected.name)} ${terminalText(selected.version)}\n${terminalText(selected.description)}\n`
+            + services.results.map(row => `${terminalText(row.key)} · ${terminalText(row.name)} · ${row.operation_count} operations`).join('\n')
+            + continuation(services, `catalog-show ${releaseId}`));
+        return;
+    }
+    let seconds = null;
+    if (action === 'add') {
+        if (options.seconds !== undefined) {
+            if (!/^[1-9][0-9]{1,8}$/.test(options.seconds))
+                throw new CliError('tool_duration_invalid', 'Use a supported --seconds value.', 2);
+            seconds = Number(options.seconds);
+        }
+        else if (tty(options) && selected.setup)
+            seconds = await selectOne('Compute duration', [
+                { value: selected.setup.default_duration_seconds, label: `${selected.setup.default_duration_seconds / 60} minutes` },
+                { value: null, label: 'Save the version without starting compute' }
+            ], options.signal);
+        else
+            throw new CliError('tool_duration_required', 'Use --seconds for an instance, or tools save for package-only setup.', 2);
+        if (seconds !== null && (!selected.setup || seconds < 60 || seconds > selected.setup.maximum_duration_seconds)) {
+            throw new CliError('tool_duration_invalid', 'Choose a compute duration within the supported catalog settings.', 2);
+        }
+    }
+    let consent = options.change === true;
+    if (!consent && tty(options))
+        consent = await selectOne(seconds === null ? `Save ${selected.name} ${selected.version} in this workspace?`
+            : `Save ${selected.name} ${selected.version} and start a separate instance for ${seconds} seconds?`, [
+            { value: false, label: 'Cancel' }, { value: true, label: seconds === null ? 'Save version' : 'Save and start instance' }
+        ], options.signal);
+    if (!consent)
+        throw new CliError('catalog_consent_required', 'Use --approve-tool-change to approve this package and any requested compute.', 2);
+    const key = options.request ? identifier(options.request) : randomUUID();
+    const usageQuote = seconds !== null ? await allocationApproval(scope, options, { release_id: releaseId, implementation_id: null,
+        dataset_id: null, restore: null, duration_seconds: seconds, launch_request_key: key }, output) : null;
+    const body = { release_id: releaseId, duration_seconds: seconds, install_consent: true, start_consent: seconds !== null, usage_quote_id: usageQuote };
+    output('catalog_setup_intent', { request_key: key, ...body }, `Catalog request: ${key}\nRecovery: tools catalog-status ${key}`);
+    let row;
+    try {
+        const accepted = await api(`${prefix}/catalog-setups`, { ...auth, method: 'POST', idempotencyKey: key, body });
+        catalogRead(accepted, catalogSetupMatches(accepted, owner, { key, input: body }));
+        row = await readSetup(key, { id: accepted.id, input: body });
+    }
+    catch {
+        try {
+            row = await readSetup(key, { input: body });
+        }
+        catch {
+            throw new CliError('catalog_acceptance_unconfirmed', `Setup acceptance is unconfirmed. No replacement was submitted. Read tools catalog-status ${key} --workspace ${scope.workspace}.`);
+        }
+    }
+    output('catalog_setup', row, text(row));
+}

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

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

package/dist/cli/src/tool-command-export.js

@@ -0,0 +1,245 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { link, lstat, open, realpath, unlink } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { access, api } from './auth.js';
+import { CliError, endpoint, responseError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { selectedWorkspace } from './world-access.js';
+import { toolLifecycleReads } from './tool-lifecycle-reads.js';
+import { toolCommandMatches, toolCommandRead, toolCommandsMatch } from './tool-command-contracts.js';
+const interactive = (options) => !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+const invalid = () => new CliError('tool_download_unconfirmed', 'The original operation file could not be confirmed. Inspect the same operation; do not repeat it to recover content.', 2);
+const fileMetadata = (row, direction) => direction === 'request' ? row.request_file : row.response_file;
+export function toolCommandDownloadHints(row) {
+    return ['request', 'response'].filter(direction => fileMetadata(row, direction) !== null).map(direction => `Download ${direction}: firedrill tools download ${row.instance_id} ${row.id} ${direction} --workspace ${row.workspace_id} --into ./tool-${row.id}-${direction}.bin --approve-download`).join('\n');
+}
+async function question(label, signal) {
+    const prompt = createInterface({ input: process.stdin, output: process.stderr, terminal: false, historySize: 0 });
+    try {
+        return (await prompt.question(label, { signal })).trim();
+    }
+    finally {
+        prompt.close();
+    }
+}
+async function chooseInstance(scope, signal) {
+    const reads = toolLifecycleReads(scope, signal);
+    let page = 1, query = '', state = 'all';
+    while (true) {
+        const rows = await reads.instances(page, query, state);
+        const selected = await selectOne('Tool instance', [
+            ...rows.results.map(row => ({ value: row.id, label: row.name, detail: `${row.version} · ${row.state}` })),
+            ...(page > 1 ? [{ value: 'previous', label: 'Previous page', detail: '' }] : []),
+            ...(rows.next ? [{ value: 'next', label: 'Next page', detail: '' }] : []),
+            { value: 'switch_scope', label: state === 'all' ? 'Show removed instances' : 'Show current instances', detail: '' },
+            { value: 'search', label: 'Search instances', detail: query }, { value: 'cancel', label: 'Cancel', detail: '' },
+        ], signal);
+        if (selected === 'cancel')
+            throw new CliError('canceled', 'No operation file was downloaded.', 130);
+        if (selected === 'next') {
+            page++;
+            continue;
+        }
+        if (selected === 'previous') {
+            page--;
+            continue;
+        }
+        if (selected === 'switch_scope') {
+            state = state === 'all' ? 'removed' : 'all';
+            page = 1;
+            continue;
+        }
+        if (selected === 'search') {
+            query = await question('Find an instance (blank for all): ', signal);
+            if (query.length > 200 || /[\u0000-\u001f\u007f-\u009f]/u.test(query))
+                throw new CliError('arguments_invalid', 'Use search text of up to 200 characters.', 2);
+            page = 1;
+            continue;
+        }
+        return identifier(selected);
+    }
+}
+async function chooseCommand(path, scope, instance, signal) {
+    let query = '', anchor, before, after;
+    while (true) {
+        const params = new URLSearchParams({ q: query, limit: '25' });
+        if (anchor)
+            params.set('anchor', anchor);
+        if (before)
+            params.set('before', before);
+        if (after)
+            params.set('after', after);
+        const page = await api(`${path}/commands?${params}`, { actor: scope.owner, workspace: scope.workspace, signal });
+        toolCommandRead(page, toolCommandsMatch(page, { workspace: scope.workspace, instance }, { query, anchor }));
+        anchor = page.anchor;
+        const selected = await selectOne('Retained operation file', [
+            ...page.results.filter(row => row.request_file !== null || row.response_file !== null).map(row => ({ value: row.id,
+                label: `${row.service_key}.${row.operation_name}`, detail: `${row.state} · ${row.id}` })),
+            ...(page.next_before ? [{ value: 'older', label: 'Older operations', detail: '' }] : []),
+            ...(page.previous_after ? [{ value: 'newer', label: 'Newer operations', detail: '' }] : []),
+            { value: 'search', label: 'Search operations', detail: query }, { value: 'cancel', label: 'Cancel', detail: '' },
+        ], signal);
+        if (selected === 'cancel')
+            throw new CliError('canceled', 'No operation file was downloaded.', 130);
+        if (selected === 'older') {
+            before = page.next_before;
+            after = undefined;
+            continue;
+        }
+        if (selected === 'newer') {
+            after = page.previous_after;
+            before = undefined;
+            continue;
+        }
+        if (selected === 'search') {
+            query = await question('Find an operation (blank for all): ', signal);
+            if (query.length > 200 || /[\u0000-\u001f\u007f-\u009f]/u.test(query))
+                throw new CliError('arguments_invalid', 'Use search text of up to 200 characters.', 2);
+            anchor = before = after = undefined;
+            continue;
+        }
+        return identifier(selected);
+    }
+}
+function sameOriginal(left, right) {
+    return left.id === right.id && left.workspace_id === right.workspace_id && left.instance_id === right.instance_id
+        && left.actor_id === right.actor_id && left.request_key === right.request_key && left.request_digest === right.request_digest
+        && left.sequence === right.sequence && left.state_epoch === right.state_epoch && left.kind === right.kind
+        && left.surface_id === right.surface_id && left.service_key === right.service_key && left.operation_name === right.operation_name
+        && left.effect === right.effect;
+}
+/** Export retained bytes only. No tool operation, lease or runtime is dispatched. */
+export async function exportToolCommand(args, options, output) {
+    if (args[0] !== 'download' || args.length > 4 || args[3] !== undefined && !['request', 'response'].includes(args[3])
+        || [options.page, options.search, options.file, options.request, options.service, options.seconds, options.state, options.usageQuote,
+            options.before, options.after, options.anchor, options.outcome].some(value => value !== undefined) || options.upload || options.change)
+        throw new CliError('arguments_invalid', 'Use tools download [instance] [command] [request|response] --into <new-file> [--approve-download]. IDs are command IDs, not request keys.', 2);
+    const tty = interactive(options);
+    const scope = await selectedWorkspace({ ...options, interactive: tty });
+    if (!args[1] && !tty)
+        throw new CliError('tool_instance_required', 'Provide the original tool instance ID.', 2);
+    const instance = args[1] ? identifier(args[1]) : await chooseInstance(scope, options.signal);
+    const path = `/api/workspaces/${identifier(scope.workspace)}/tools/instances/${instance}`;
+    if (!args[2] && !tty)
+        throw new CliError('tool_command_required', 'Provide the original command ID from tools activity or result. Do not repeat the operation.', 2);
+    const command = args[2] ? identifier(args[2]) : await chooseCommand(path, scope, instance, options.signal);
+    const read = async () => {
+        const row = await api(`${path}/commands/${command}`, { actor: scope.owner, workspace: scope.workspace, signal: options.signal });
+        return toolCommandRead(row, toolCommandMatches(row, { workspace: scope.workspace, instance }, { id: command }));
+    };
+    const original = await read();
+    const available = ['request', 'response'].filter(direction => fileMetadata(original, direction) !== null);
+    if (!available.length)
+        throw new CliError('tool_file_unavailable', 'This operation has no currently retained downloadable files. Withheld, expired or missing content cannot be recreated by repeating the operation.', 2);
+    let direction = args[3];
+    if (!direction && available.length === 1)
+        direction = available[0];
+    if (!direction && tty)
+        direction = await selectOne('File to download', available.map(value => ({ value, label: value === 'request' ? 'Original request' : 'Original response' })), options.signal);
+    if (!direction)
+        throw new CliError('tool_file_direction_required', 'Choose request or response after the command ID.', 2);
+    const expected = fileMetadata(original, direction);
+    if (!expected)
+        throw new CliError('tool_file_unavailable', 'The selected original file is withheld, expired or not retained. No operation was repeated.', 2);
+    const into = options.into ?? (tty ? await question('Save this private file to a new path: ', options.signal) : '');
+    if (!into.trim() || /[\u0000-\u001f\u007f-\u009f]/u.test(into))
+        throw new CliError('tool_download_path_required', 'Use --into <new-file>. Existing files are never replaced.', 2);
+    output('tool_download_review', { instance_id: instance, command_id: command, direction, file: expected }, `Original ${direction} · ${command}\n${expected.size.toLocaleString()} bytes. This private device copy will not be erased by cloud retention or withdrawal.`);
+    if (!options.approveDownload) {
+        if (!tty)
+            throw new CliError('tool_download_consent_required', 'Use --approve-download to save this retained private operation file on the device.', 2);
+        if (!await selectOne('Save this private operation file?', [{ value: false, label: 'Cancel' }, { value: true, label: 'Download file' }], options.signal))
+            return;
+    }
+    const chosen = resolve(into), parent = await realpath(dirname(chosen)), folder = await lstat(parent), destination = join(parent, basename(chosen));
+    const ownedFolder = (value) => value.isDirectory()
+        && (process.platform === 'win32' || (!process.getuid || value.uid === process.getuid()) && !(value.mode & 0o022));
+    if (!ownedFolder(folder))
+        throw new CliError('tool_download_directory_invalid', 'Choose a directory owned by this OS user without shared write permission.', 2);
+    try {
+        await lstat(destination);
+        throw new CliError('tool_download_file_exists', 'The chosen file already exists. Choose a new path.', 2);
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+    }
+    const partial = join(parent, `.firedrill-tool-${randomUUID()}.partial`), file = await open(partial, 'wx', 0o600);
+    let held = null;
+    try {
+        held = await file.stat();
+        await access(async (token) => {
+            const response = await fetch(endpoint(`${path}/commands/${command}/files/${direction}`), { redirect: 'error', credentials: 'omit',
+                headers: { Authorization: `Bearer ${token}`, 'X-Firedrill-Actor': scope.owner, 'X-Firedrill-Workspace': scope.workspace, 'Accept-Encoding': 'identity' },
+                signal: AbortSignal.any([options.signal, AbortSignal.timeout(120000)]) });
+            if (response.status !== 200) {
+                await response.body?.cancel();
+                throw responseError(null, response.status);
+            }
+            if (response.headers.get('content-length') !== String(expected.size) || response.headers.get('x-content-sha256') !== expected.sha256
+                || ![null, 'identity'].includes(response.headers.get('content-encoding')) || !response.body && expected.size !== 0) {
+                await response.body?.cancel();
+                throw invalid();
+            }
+            let size = 0;
+            const digest = createHash('sha256');
+            if (response.body) {
+                const reader = response.body.getReader();
+                try {
+                    while (true) {
+                        options.signal.throwIfAborted();
+                        const part = await reader.read();
+                        if (part.done)
+                            break;
+                        size += part.value.byteLength;
+                        if (size > expected.size)
+                            throw invalid();
+                        digest.update(part.value);
+                        let offset = 0;
+                        while (offset < part.value.byteLength) {
+                            const written = await file.write(part.value, offset, part.value.byteLength - offset);
+                            if (!written.bytesWritten)
+                                throw invalid();
+                            offset += written.bytesWritten;
+                        }
+                    }
+                }
+                finally {
+                    await reader.cancel().catch(() => undefined);
+                    reader.releaseLock();
+                }
+            }
+            if (size !== expected.size || digest.digest('hex') !== expected.sha256)
+                throw invalid();
+        });
+        const fresh = await read(), currentFile = fileMetadata(fresh, direction);
+        if (!sameOriginal(original, fresh) || !currentFile || currentFile.size !== expected.size || currentFile.sha256 !== expected.sha256)
+            throw invalid();
+        await file.sync();
+        options.signal.throwIfAborted();
+        const current = await lstat(partial), currentFolder = await lstat(parent);
+        if (!current.isFile() || current.dev !== held.dev || current.ino !== held.ino || current.size !== expected.size
+            || process.platform !== 'win32' && !!(current.mode & 0o077) || !ownedFolder(currentFolder)
+            || currentFolder.dev !== folder.dev || currentFolder.ino !== folder.ino)
+            throw invalid();
+        options.signal.throwIfAborted();
+        await link(partial, destination);
+        output('tool_file_downloaded', { instance_id: instance, command_id: command, direction, path: destination, file: expected }, `File saved to ${terminalText(destination)}\n${expected.size.toLocaleString()} bytes · SHA-256 ${expected.sha256}\nNo tool operation was repeated.`);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        if (options.signal.aborted)
+            throw new CliError('canceled', 'The download was canceled. Inspect the chosen path before retrying; no existing file was replaced.', 130);
+        throw new CliError('tool_download_unconfirmed', 'The download did not finish. Inspect the chosen path before retrying; no existing file was replaced. Do not repeat the tool operation.');
+    }
+    finally {
+        const identity = held ?? await file.stat().catch(() => null);
+        await file.close().catch(() => undefined);
+        const current = await lstat(partial).catch(() => null);
+        if (identity && current?.isFile() && current.dev === identity.dev && current.ino === identity.ino)
+            await unlink(partial).catch(() => undefined);
+    }
+}

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

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

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

@@ -0,0 +1,23 @@
+import { api } from './auth.js';
+import { identifier } from './world-contracts.js';
+import { toolConnectionRead, toolConnectionsMatch, toolConnectionMatches, toolConnectionAccepted, toolConnectionOptionsMatch } from './tool-connection-contracts.js';
+export function toolConnectionReads(owner, instance, signal) {
+    const scope = { workspace: owner.workspace, actor: owner.owner, instance: identifier(instance) };
+    const prefix = `/api/workspaces/${scope.workspace}/tools/instances/${scope.instance}`;
+    const auth = { actor: owner.owner, workspace: owner.workspace, signal };
+    return {
+        async page(page = 1, query = '') {
+            const value = await api(`${prefix}/connections?page=${page}&q=${encodeURIComponent(query)}`, auth);
+            return toolConnectionRead(value, toolConnectionsMatch(value, scope, query, page));
+        },
+        async options(page = 1, query = '', epoch) {
+            const value = await api(`${prefix}/connection-options?page=${page}&q=${encodeURIComponent(query)}`, auth);
+            return toolConnectionRead(value, toolConnectionOptionsMatch(value, { ...scope, epoch }, query, page));
+        },
+        async original(key, selected = {}) {
+            const value = await api(`${prefix}/connection-requests/${identifier(key)}`, auth);
+            return toolConnectionRead(value, selected.input ? await toolConnectionAccepted(value, scope, key, selected.input, selected)
+                : toolConnectionMatches(value, scope, { ...selected, key }));
+        },
+    };
+}