firedrill-run 2.2.4 → 3.0.0

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

@@ -0,0 +1,311 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectMany, selectOne, terminalText } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { selectedWorkspace } from './world-access.js';
+import { catalogRead, catalogPageMatches } from './catalog-contracts.js';
+import { packageRead, toolVersionPageMatches } from './tool-package-contracts.js';
+import { datasetReads } from './dataset-reads.js';
+import { toolLifecycleReads } from './tool-lifecycle-reads.js';
+import { allocationQuote } from './tool-runtime.js';
+import { creditAmount } from './credit-format.js';
+import { toolGroupReads } from './tool-group-reads.js';
+import { toolGroupRead, toolGroupMatches, toolGroupAccepted } from './tool-group-contracts.js';
+const tty = (options) => !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+const selectionKey = (one) => 'release_id' in one ? `release:${one.release_id}` : `version:${one.implementation_id}`;
+function text(row) {
+    return `${terminalText(row.name)}\nSetup: ${row.id}\nRequest: ${row.request_key}\n${row.counts.selected} selected · ${row.counts.running} running`
+        + (row.counts.pending ? ` · ${row.counts.pending} awaiting setup` : '')
+        + (row.counts.failed + row.counts.refused ? ` · ${row.counts.failed + row.counts.refused} failed` : '')
+        + (row.counts.closing ? ` · ${row.counts.closing} stopping` : '')
+        + (row.counts.closed ? ` · ${row.counts.closed} closed` : '')
+        + (row.counts.canceled ? ` · ${row.counts.canceled} canceled before startup` : '')
+        + `\nExpires: ${row.expires_at}${row.stop_requested_at ? '\nStop requested. Inspect each instance for observed cleanup.' : ''}`;
+}
+async function inputFile(path, signal) {
+    const filename = resolve(path), before = await lstat(filename);
+    if (!before.isFile() || before.isSymbolicLink() || before.size < 1 || before.size > 4 * 1024 ** 2) {
+        throw new CliError('tool_group_input_invalid', 'Choose a regular setup JSON file within request capacity.', 2);
+    }
+    const file = await open(filename, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const held = await file.stat();
+        if (held.dev !== before.dev || held.ino !== before.ino || held.size !== before.size || held.mtimeMs !== before.mtimeMs)
+            throw new Error();
+        const chunks = [];
+        let bytes = 0;
+        for await (const chunk of file.createReadStream({ autoClose: false })) {
+            signal.throwIfAborted();
+            bytes += chunk.length;
+            if (bytes > 4 * 1024 ** 2)
+                throw new Error();
+            chunks.push(Buffer.from(chunk));
+        }
+        const after = await file.stat();
+        if (bytes !== held.size || after.size !== held.size || after.mtimeMs !== held.mtimeMs || after.ctimeMs !== held.ctimeMs)
+            throw new Error();
+        const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+        if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).sort().join(',') !== 'duration_seconds,name,selections')
+            throw new Error();
+        const row = value;
+        if (typeof row.name !== 'string' || row.name !== row.name.trim() || !row.name || row.name.length > 120 || /[\u0000-\u001f\u007f]/.test(row.name)
+            || !Number.isSafeInteger(row.duration_seconds) || row.duration_seconds < 60 || !Array.isArray(row.selections) || !row.selections.length
+            || !row.selections.every(one => one && (Object.keys(one).sort().join(',') === 'dataset_id,implementation_id,usage_quote_id'
+                && 'implementation_id' in one && identifier(one.implementation_id) && (one.dataset_id === null || identifier(one.dataset_id))
+                || Object.keys(one).sort().join(',') === 'dataset_id,release_id,usage_quote_id' && 'release_id' in one && identifier(one.release_id) && one.dataset_id === null)
+                && typeof one.usage_quote_id === 'string' && identifier(one.usage_quote_id))
+            || new Set(row.selections.map(selectionKey)).size !== row.selections.length)
+            throw new Error();
+        return row;
+    }
+    catch {
+        signal.throwIfAborted();
+        throw new CliError('tool_group_input_invalid', 'Provide name, duration_seconds and selections of implementation_id/dataset_id or release_id with dataset_id null. No tools were requested.', 2);
+    }
+    finally {
+        await file.close();
+    }
+}
+async function chooseVersions(prefix, auth, options, maximum) {
+    const selected = new Map();
+    let page = 1, source = 'release';
+    while (true) {
+        const rows = source === 'release'
+            ? await api(`${prefix}/library?page=${page}&q=${encodeURIComponent(options.search ?? '')}`, auth).then(value => catalogRead(value, catalogPageMatches(value, prefix.split('/')[3], options.search ?? '', page)))
+            : await api(`${prefix}/catalog?state=inspected&page=${page}&q=${encodeURIComponent(options.search ?? '')}`, auth).then(value => packageRead(value, toolVersionPageMatches(value, prefix.split('/')[3], { page, query: options.search ?? '' })));
+        const available = rows.results.filter(one => source === 'release' ? one.available && one.saved_version?.state !== 'revoked' : one.state === 'inspected');
+        const availableIds = new Set(available.map(one => one.id));
+        for (const row of rows.results)
+            if (!availableIds.has(row.id))
+                selected.delete(`${source}:${row.id}`);
+        if (available.length) {
+            const checked = new Set(await selectMany(`${source === 'release' ? 'Catalog' : 'Saved versions'} · page ${page}`, available.map(one => ({ value: `${source}:${one.id}`,
+                label: one.name, detail: `Version ${one.version}` })), options.signal, [...selected.keys()]));
+            const proposed = new Map(selected);
+            for (const row of rows.results) {
+                const key = `${source}:${row.id}`;
+                if (checked.has(key))
+                    proposed.set(key, { id: row.id, name: row.name, version: row.version, source });
+                else
+                    proposed.delete(key);
+            }
+            if (proposed.size > maximum) {
+                process.stderr.write(`Choose at most ${maximum} tools in this setup. Your previous selection is unchanged.\n`);
+                continue;
+            }
+            selected.clear();
+            for (const [key, version] of proposed)
+                selected.set(key, version);
+        }
+        const action = await selectOne(`${selected.size} selected`, [
+            ...(selected.size ? [{ value: 'finish', label: 'Continue with selected tools' }] : []),
+            ...(rows.next ? [{ value: 'next', label: 'Next page' }] : []), ...(page > 1 ? [{ value: 'previous', label: 'Previous page' }] : []),
+            { value: 'source', label: source === 'release' ? 'Browse saved versions' : 'Browse catalog' },
+            { value: 'cancel', label: 'Cancel' }
+        ], options.signal);
+        if (action === 'cancel')
+            throw new CliError('canceled', 'No tools were requested.', 130);
+        if (action === 'finish')
+            return [...selected.values()];
+        if (action === 'source') {
+            source = source === 'release' ? 'version' : 'release';
+            page = 1;
+            continue;
+        }
+        page += action === 'next' ? 1 : -1;
+    }
+}
+async function chooseDataset(prefix, version, auth, signal) {
+    let page = 1;
+    if (!auth?.actor || !auth.workspace)
+        throw new CliError('tool_dataset_scope_invalid', 'Choose a workspace before selecting data.', 2);
+    const reads = datasetReads(prefix, { owner: auth.actor, workspace: auth.workspace }, signal);
+    while (true) {
+        const rows = await reads.page({ implementation: version, state: 'retained', page });
+        const value = await selectOne('Starting data', [{ value: 'packaged', label: 'Packaged data' },
+            ...rows.results.filter(one => one.available).map(one => ({ value: one.id, label: one.name, detail: `Version ${one.version}` })),
+            ...(rows.next ? [{ value: 'next', label: 'Next page' }] : []), ...(page > 1 ? [{ value: 'previous', label: 'Previous page' }] : [])], signal);
+        if (value === 'packaged')
+            return null;
+        if (value === 'next')
+            page++;
+        else if (value === 'previous')
+            page--;
+        else
+            return identifier(value);
+    }
+}
+export async function toolGroupCommand(args, options, output) {
+    const action = args[0] === 'start' ? 'start-many' : args[0], starting = action === 'start-many', paged = ['setups', 'setup-members', 'start-many'].includes(action);
+    if (!['setups', 'setup', 'setup-members', 'setup-status', 'start-many', 'stop-setup'].includes(action)
+        || args.length > (['setups', 'start-many'].includes(action) ? 1 : 2) || options.upload || options.service !== undefined
+        || !paged && (options.page !== undefined || options.search !== undefined) || starting && options.page !== undefined
+        || !starting && (options.file !== undefined || options.request !== undefined || options.seconds !== undefined)
+        || !starting && action !== 'stop-setup' && options.change || starting && options.file && options.seconds !== undefined
+        || options.usageQuote !== 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 start [--file setup.json], setups, setup <id>, setup-members <id>, setup-status <request>, or stop-setup <id>. Setup files carry one approved usage_quote_id per tool.', 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 reads = toolGroupReads(scope, options.signal), owner = { workspace: scope.workspace, actor: scope.owner };
+    const continuation = (row, command) => {
+        const quote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
+        return `\nPage ${row.page}; ${row.count} matching items.${row.next ? `\nNext: firedrill tools ${command} --workspace ${scope.workspace} --page ${row.page + 1}${options.search ? ' --search ' + quote(options.search) : ''}` : ''}`;
+    };
+    if (action === 'setups') {
+        const rows = await reads.page(Number(options.page ?? 1), options.search ?? '');
+        output('tool_setups', rows, (rows.results.map(text).join('\n\n') || 'No tool setups in this workspace.') + continuation(rows, 'setups'));
+        return;
+    }
+    if (action === 'setup-status') {
+        const row = await reads.original(identifier(args[1] ?? ''));
+        output('tool_setup', row, text(row));
+        return;
+    }
+    if (!starting) {
+        let chosen = args[1], page = 1;
+        while (!chosen && tty(options)) {
+            const rows = await reads.page(page);
+            const value = await selectOne('Tool setup', [...rows.results.map(one => ({ value: one.id, label: one.name,
+                    detail: `${one.counts.selected} tools · ${one.counts.running} running · ${one.counts.failed + one.counts.refused} failed` })),
+                ...(rows.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', 'Nothing changed.', 130);
+            if (value === 'next')
+                page++;
+            else if (value === 'previous')
+                page--;
+            else
+                chosen = identifier(value);
+        }
+        const id = identifier(chosen ?? ''), path = `${prefix}/setups/${id}`;
+        if (action === 'setup-members') {
+            const rows = await reads.members(id, Number(options.page ?? 1), options.search ?? '');
+            output('tool_setup_members', rows, (rows.results.map(one => `${terminalText(one.name)} ${terminalText(one.version)}: ${one.instance?.removal ? one.instance.removal.completed_at ? 'removed' : 'removing'
+                : one.instance?.state === 'active' && !one.instance.observation_current ? 'awaiting observation' : one.instance?.state ?? one.state}`
+                + `${one.instance ? '\nInstance: ' + one.instance.id : ''}\nStarting data: ${one.dataset ? terminalText(one.dataset.name) + ' version ' + one.dataset.version : 'packaged data'}`
+                + (one.catalog_request_key ? `\nCatalog setup: tools catalog-status ${one.catalog_request_key}` : '')
+                + (one.problem || one.instance?.problem ? '\n' + terminalText(one.problem || one.instance?.problem || '') : '')).join('\n\n') || 'No matching tools in this setup.') + continuation(rows, `setup-members ${id}`));
+            return;
+        }
+        const original = await reads.detail(id);
+        if (action === 'setup') {
+            output('tool_setup', original, text(original));
+            return;
+        }
+        const consent = options.change || tty(options) && await selectOne(`Stop ${original.counts.selected} tools in ${original.name}? Pending setups will be canceled. Saved history remains.`, [{ value: false, label: 'Cancel' }, { value: true, label: 'Stop tools' }], options.signal);
+        if (!consent)
+            throw new CliError('tool_stop_consent_required', 'Nothing changed. Use --approve-tool-change for explicit automation consent.', 2);
+        const row = await api(path, { ...auth, method: 'DELETE', body: { stop_consent: true } });
+        toolGroupRead(row, toolGroupMatches(row, owner, { id, digest: original.request_digest, stopped: true }));
+        const recorded = await reads.detail(id, { digest: original.request_digest, stopped: true });
+        output('tool_setup', recorded, text(recorded));
+        return;
+    }
+    const { setup } = await toolLifecycleReads(scope, options.signal).instances();
+    let value;
+    if (options.file)
+        value = await inputFile(options.file, options.signal);
+    else {
+        if (!tty(options))
+            throw new CliError('tool_group_input_required', 'Use --file setup.json with name, duration_seconds and selections. No tools were requested.', 2);
+        const versions = await chooseVersions(prefix, auth, options, setup.maximum_tools);
+        value = { name: versions.slice(0, 2).map(one => terminalText(one.name)).join(', ').trim().slice(0, 120) || 'Tools', duration_seconds: options.seconds === undefined ? setup.default_duration_seconds : Number(options.seconds),
+            selections: versions.map(one => one.source === 'release' ? { release_id: one.id, dataset_id: null } : { implementation_id: one.id, dataset_id: null }) };
+        const savedVersions = versions.filter(one => one.source === 'version');
+        const data = savedVersions.length ? await selectOne('Starting data', [{ value: 'packaged', label: 'Packaged data for all tools' }, { value: 'saved', label: 'Choose saved datasets for saved versions' }], options.signal) : 'packaged';
+        if (data === 'saved') {
+            let page = 1;
+            while (true) {
+                const rows = savedVersions.slice((page - 1) * 25, page * 25);
+                const selected = await selectOne('Choose a tool to change its starting data', [
+                    { value: 'finish', label: 'Continue' }, ...rows.map(one => ({ value: one.id, label: one.name, detail: `Version ${one.version}` })),
+                    ...(page * 25 < savedVersions.length ? [{ value: 'next', label: 'Next page' }] : []), ...(page > 1 ? [{ value: 'previous', label: 'Previous page' }] : [])
+                ], options.signal);
+                if (selected === 'finish')
+                    break;
+                if (selected === 'next')
+                    page++;
+                else if (selected === 'previous')
+                    page--;
+                else {
+                    const choice = value.selections.find(one => 'implementation_id' in one && one.implementation_id === selected);
+                    if (!choice || !('implementation_id' in choice))
+                        throw new CliError('tool_group_input_invalid', 'The selected saved version changed. No tools were requested.', 2);
+                    choice.dataset_id = await chooseDataset(prefix, selected, auth, options.signal);
+                }
+            }
+        }
+    }
+    return startToolGroup(scope, value, options, output);
+}
+export async function startToolGroup(scope, value, options, output, beforeDispatch) {
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const prefix = `/api/workspaces/${scope.workspace}/tools`, owner = { workspace: scope.workspace, actor: scope.owner };
+    const reads = toolGroupReads(scope, options.signal);
+    const { setup } = await toolLifecycleReads(scope, options.signal).instances();
+    if (!value.selections.length || value.selections.length > setup.maximum_tools || value.duration_seconds > setup.maximum_duration_seconds || !Number.isSafeInteger(value.duration_seconds) || value.duration_seconds < 60) {
+        throw new CliError('tool_group_capacity', 'Choose a tool count and duration within configured setup capacity. No tools were requested.', 2);
+    }
+    if (!tty(options) && !options.change)
+        throw new CliError('tool_start_consent_required', 'No tools were requested. Use --approve-tool-change for explicit automation consent.', 2);
+    const key = identifier(options.request ?? randomUUID());
+    output('tool_setup_intent', { request_key: key, selection_count: value.selections.length, duration_seconds: value.duration_seconds }, `Setup request: ${key}\nIf interrupted, use tools setup-status ${key}. Never create a replacement request to recover an uncertain reply.`);
+    const selections = [];
+    const quotes = [];
+    for (const chosen of value.selections) {
+        const quoteId = chosen.usage_quote_id;
+        // File-based automation must carry one previously approved quote per child.
+        // Interactive users review the combined bounded budget before one dispatch.
+        let launchKey = randomUUID();
+        if (quoteId) {
+            const quoted = await api(`/api/workspaces/${scope.workspace}/billing/usage/quotes/${identifier(quoteId)}`, auth);
+            if (!quoted?.scope || typeof quoted.scope.launch_request_key !== 'string')
+                throw new CliError('billing_scope_mismatch', 'Review a current runtime quote for each selected tool. No tools were requested.', 2);
+            launchKey = identifier(quoted.scope.launch_request_key);
+        }
+        const quote = await allocationQuote(scope, { ...options, usageQuote: quoteId }, {
+            implementation_id: 'implementation_id' in chosen ? chosen.implementation_id : null,
+            release_id: 'release_id' in chosen ? chosen.release_id : null, dataset_id: chosen.dataset_id,
+            restore: null, duration_seconds: value.duration_seconds, launch_request_key: launchKey
+        });
+        if (quotes.length && (quote.credit_scale !== quotes[0].credit_scale || quote.denomination !== quotes[0].denomination))
+            throw new CliError('billing_policy_changed', 'The credit policy changed during review. No tools were requested. Review the current selection again.', 2);
+        quotes.push(quote);
+        selections.push({ ...chosen, usage_quote_id: quote.id });
+    }
+    const maximum = quotes.reduce((total, quote) => total + BigInt(quote.maximum_units), 0n);
+    if (maximum > BigInt(Number.MAX_SAFE_INTEGER))
+        throw new CliError('billing_budget_capacity', 'This combined budget needs a smaller selection. No tools were requested.', 2);
+    output('tool_setup_budget', { workspace_id: scope.workspace, request_key: key, selection_count: selections.length,
+        duration_seconds: value.duration_seconds, maximum_units: Number(maximum), credit_scale: quotes[0].credit_scale,
+        denomination: quotes[0].denomination, quotes: quotes.map(quote => ({ id: quote.id, maximum_units: quote.maximum_units, expires_at: quote.expires_at })) }, `Up to ${creditAmount(Number(maximum), quotes[0].credit_scale)} credits for ${selections.length} ${selections.length === 1 ? 'tool' : 'tools'} for ${value.duration_seconds} seconds, including startup and waiting for capacity. Unused credits are released after cleanup.`);
+    if (tty(options) && !await selectOne('Start the selected tools with this runtime budget?', [{ value: false, label: 'Cancel' }, { value: true, label: selections.length === 1 ? 'Start tool' : `Start ${selections.length} tools` }], options.signal))
+        throw new CliError('canceled', 'No tools were requested.', 130);
+    await beforeDispatch?.();
+    options.signal.throwIfAborted();
+    if (quotes.some(quote => Date.parse(quote.expires_at) <= Date.now()))
+        throw new CliError('billing_scope_mismatch', 'The runtime quotes expired before startup. No tools were requested. Review the current selection again.', 2);
+    const input = { ...value, selections, start_consent: true };
+    let recorded;
+    try {
+        const row = await api(`${prefix}/setups`, { ...auth, method: 'POST', idempotencyKey: key, body: input });
+        toolGroupRead(row, await toolGroupAccepted(row, owner, key, input));
+        recorded = await reads.original(key, { input, id: row.id, digest: row.request_digest });
+    }
+    catch {
+        try {
+            recorded = await reads.original(key, { input });
+        }
+        catch {
+            throw new CliError('tool_group_acceptance_unconfirmed', `Setup acceptance is unconfirmed. No replacement was submitted. Use tools setup-status ${key} --workspace ${scope.workspace}.`, 2);
+        }
+    }
+    output('tool_setup', recorded, text(recorded) + `\nUse tools setup-members ${recorded.id} for each original instance, then tools open <instance> for its portal view.`);
+}

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

@@ -0,0 +1,186 @@
+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 { choosePaged } from './configuration.js';
+import { requestInput as argumentsFile } from './request-input.js';
+import { packageReads } from './tool-package-reads.js';
+import { toolLifecycleReads } from './tool-lifecycle-reads.js';
+import { toolStateReads } from './tool-state-reads.js';
+import { toolCommandRead, toolCommandMatches, toolCommandsMatch } from './tool-command-contracts.js';
+import { toolCommandDownloadHints } from './tool-command-export.js';
+const interactive = (options) => !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+function commandText(row) {
+    const schema = { matched: 'Matches declared schema', mismatch: 'Does not match declared schema',
+        not_json: 'Response is not JSON', missing_structured: 'No structured result',
+        not_applicable: row.response?.transport === 'http' && row.response.response_encoding === 'binary' ? 'Binary response' : 'Text response' }[row.response?.schema_status ?? ''] ?? 'Schema unavailable';
+    const downloads = toolCommandDownloadHints(row);
+    return `${row.service_key}.${row.operation_name}: ${row.state}\nCommand: ${row.id}\nRequest: ${row.request_key}`
+        + (row.response?.transport === 'surface' ? `\nBrowser receipt: ${row.response.surface_state}` : row.response ? `\n${row.response.transport === 'mcp' ? `MCP tool error: ${row.response.mcp_is_error ? 'yes' : 'no'}`
+            : `HTTP ${row.response.http_status}`}. ${schema}. ${row.response.body_size} bytes.` : '')
+        + (row.response_withheld ? '\nResponse content was withheld from history.' : '')
+        + (row.problem ? '\n' + row.problem : '') + (downloads ? '\n' + downloads : '');
+}
+export async function toolInstanceCommand(args, options, output) {
+    const action = args[0];
+    if (options.state !== undefined && (action !== 'instances' || !['all', 'active', 'closed', 'removed'].includes(options.state)))
+        throw new CliError('arguments_invalid', 'Use tools instances --state all|active|closed|removed.', 2);
+    if (args.length > (action === 'call' ? 4 : action === 'result' ? 3 : 2)
+        || !['instances', 'removed', 'activity', 'checkpoints'].includes(action) && (options.page !== undefined || options.search !== undefined)
+        || action === 'activity' && options.page !== undefined
+        || action !== 'activity' && [options.before, options.after, options.anchor, options.outcome].some(one => one !== undefined)
+        || ['instances', 'removed'].includes(action) && args.length > 1 || options.service !== undefined || options.upload
+        || options.seconds !== undefined || action !== 'call' && (options.file !== undefined || options.request !== undefined || options.change)) {
+        throw new CliError('arguments_invalid', 'Use tools instances, instance <id>, activity <id>, checkpoints [instance], result <instance> <request>, or call [instance] [service] [operation] [--file arguments.json].', 2);
+    }
+    if (options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page) || (options.search?.length ?? 0) > 200) {
+        throw new CliError('arguments_invalid', 'Use a positive page and a search up to 200 characters.', 2);
+    }
+    const scope = await selectedWorkspace({ ...options, interactive: interactive(options) });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const prefix = `/api/workspaces/${scope.workspace}/tools`;
+    const lifecycle = toolLifecycleReads(scope, options.signal);
+    const query = `page=${options.page ?? '1'}&q=${encodeURIComponent(options.search ?? '')}`;
+    if (['instances', 'removed'].includes(action)) {
+        const state = action === 'removed' ? 'removed' : (options.state ?? 'all');
+        const page = await lifecycle.instances(Number(options.page ?? 1), options.search ?? '', state);
+        const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+        output('tool_instances', page, (page.results.map(one => `${one.id}  ${one.name} ${one.version} · ${one.removal ? one.removal.completed_at ? 'removed' : 'removing' : one.state}`).join('\n') || 'No matching tool instances in this workspace.')
+            + `\nPage ${page.page}; ${page.count} instances.${page.next ? `\nNext: firedrill tools ${action} --workspace ${scope.workspace} --page ${page.page + 1}${action === 'instances' ? ` --state ${state}` : ''}${options.search ? ` --search ${quote(options.search)}` : ''}` : ''}`);
+        return;
+    }
+    let instance = args[1] ? identifier(args[1]) : undefined;
+    if (!instance && interactive(options)) {
+        let page = 1;
+        while (!instance) {
+            const result = await lifecycle.instances(page, '', action === 'call' ? 'active' : 'all');
+            const selected = await selectOne('Tool instance', [
+                ...result.results.map(one => ({ value: one.id, label: one.name, detail: `${one.version} · ${one.state}` })),
+                ...(result.next ? [{ value: '__next__', label: 'Next page' }] : []), ...(page > 1 ? [{ value: '__previous__', label: 'Previous page' }] : []),
+                { value: '__cancel__', label: 'Cancel' },
+            ], options.signal);
+            if (selected === '__cancel__')
+                throw new CliError('canceled', 'No operation was submitted.', 130);
+            if (selected === '__next__')
+                page++;
+            else if (selected === '__previous__')
+                page--;
+            else
+                instance = identifier(selected);
+        }
+    }
+    if (!instance)
+        throw new CliError('tool_instance_required', 'Provide a tool instance ID from tools instances.', 2);
+    const path = `${prefix}/instances/${instance}`;
+    const commandScope = { workspace: scope.workspace, instance, actor: scope.owner };
+    if (action === 'instance') {
+        const row = await lifecycle.instance(instance);
+        output('tool_instance', row, `${row.name} ${row.version} · ${row.removal ? row.removal.completed_at ? 'removed' : 'removing' : row.state}${row.problem ? '\n' + row.problem : ''}`
+            + (row.removal ? '\nSaved activity and data follow workspace retention.' : ''));
+        return;
+    }
+    if (action === 'activity') {
+        const sequence = (value, zero = false) => value === undefined
+            || /^(0|[1-9][0-9]{0,18})$/.test(value) && BigInt(value) >= (zero ? 0n : 1n) && BigInt(value) < 2n ** 63n;
+        if (!sequence(options.before) || !sequence(options.after) || !sequence(options.anchor, true)
+            || options.before !== undefined && options.after !== undefined
+            || (options.before !== undefined || options.after !== undefined) && options.anchor === undefined
+            || options.outcome !== undefined && !['queued', 'publishing', 'accepted', 'observed', 'not_dispatched', 'unknown'].includes(options.outcome)) {
+            throw new CliError('arguments_invalid', 'Use an activity outcome and the saved --before or --after position with --anchor.', 2);
+        }
+        const params = new URLSearchParams({ q: options.search ?? '' });
+        for (const name of ['before', 'after', 'anchor', 'outcome'])
+            if (options[name] !== undefined)
+                params.set(name, options[name]);
+        const page = await api(`${path}/commands?${params}`, auth);
+        toolCommandRead(page, toolCommandsMatch(page, commandScope, { query: options.search, outcome: options.outcome, anchor: options.anchor }));
+        const quoted = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
+        const original = `firedrill tools activity ${instance} --workspace ${scope.workspace}`
+            + (options.search ? ` --search ${quoted(options.search)}` : '') + (options.outcome ? ` --outcome ${options.outcome}` : '');
+        const continuation = (page.next_before ? `\nOlder: ${original} --anchor ${page.anchor} --before ${page.next_before}` : '')
+            + (page.previous_after ? `\nNewer: ${original} --anchor ${page.anchor} --after ${page.previous_after}` : '');
+        output('tool_activity', page, (page.results.map(commandText).join('\n\n') || 'No matching operation history in this instance.') + continuation);
+        return;
+    }
+    if (action === 'checkpoints') {
+        const page = await toolStateReads(scope, instance, options.signal).checkpoints(Number(options.page ?? 1), options.search ?? '');
+        const quote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
+        output('tool_data_checkpoints', page, (page.results.map(one => `${one.id}  ${one.scope === 'declared_stateless' ? one.kind === 'baseline' ? 'Startup record' : 'Closing record' : one.kind} · ${one.captured_at}\n${one.available ? one.scope === 'declared_stateless' ? 'No persistent data declared. Service memory is not included.' : 'Saved data available.' : one.problem ?? 'Saved data unavailable.'}`).join('\n\n') || 'No data checkpoints in this instance.')
+            + `\nPage ${page.page}; ${page.count} checkpoints.${page.next ? `\nNext: firedrill tools checkpoints ${instance} --workspace ${scope.workspace} --page ${page.page + 1}${options.search ? ' --search ' + quote(options.search) : ''}` : ''}`);
+        return;
+    }
+    if (action === 'result') {
+        const key = identifier(args[2] ?? '');
+        const row = await api(`${path}/requests/${key}`, auth);
+        toolCommandRead(row, toolCommandMatches(row, commandScope, { key }));
+        output('tool_operation_result', row, commandText(row));
+        return;
+    }
+    const row = await lifecycle.instance(instance);
+    if (!row.observation_current)
+        throw new CliError('tool_instance_not_ready', 'Wait for a current tool observation before submitting an operation.', 2);
+    const packagePath = `${prefix}/implementations/${identifier(row.implementation_id)}`;
+    const packages = packageReads(scope, options.signal);
+    const version = await packages.version(row.implementation_id);
+    if (version.state !== 'inspected')
+        throw new CliError('tool_version_unavailable', 'The original tool version is no longer available. No operation was submitted.', 2);
+    let service = args[2];
+    if (!service && interactive(options)) {
+        const chosen = await choosePaged('Service', `${packagePath}/services`, scope, options, one => ({ label: one.name, detail: `${one.operation_count} operations` }), false, (page, search) => packages.services(version, page, search));
+        service = chosen?.key;
+    }
+    if (!service || !/^[a-z][a-z0-9_-]{0,79}$/.test(service))
+        throw new CliError('tool_service_required', 'Choose a service from tools services for this instance version.', 2);
+    const selected = await packages.service(version, service);
+    if (selected.key !== service || selected.implementation_id !== row.implementation_id || selected.contract_digest !== version.contract_digest) {
+        throw new CliError('tool_version_unavailable', 'The original tool version changed. No operation was submitted.', 2);
+    }
+    let operation = args[3];
+    if (!operation && interactive(options)) {
+        let page = 1;
+        while (!operation) {
+            const result = await packages.operations(version, service, page);
+            const selected = await selectOne('Operation', [
+                ...result.results.filter(one => one.transport.kind === 'mcp' || one.transport.kind === 'http' && ['json', 'query', 'form', 'multipart', 'text', 'base64', 'none'].includes(one.transport.encoding ?? ''))
+                    .map(one => ({ value: one.name, label: one.name, detail: one.effect })),
+                ...(result.next ? [{ value: '__next__', label: 'Next page' }] : []), ...(page > 1 ? [{ value: '__previous__', label: 'Previous page' }] : []),
+                { value: '__cancel__', label: 'Cancel' },
+            ], options.signal);
+            if (selected === '__cancel__')
+                throw new CliError('canceled', 'No operation was submitted.', 130);
+            if (selected === '__next__')
+                page++;
+            else if (selected === '__previous__')
+                page--;
+            else
+                operation = selected;
+        }
+    }
+    if (!operation || !/^[A-Za-z][A-Za-z0-9_.-]{0,127}$/.test(operation))
+        throw new CliError('tool_operation_required', 'Choose an operation name from tools operations.', 2);
+    await packages.operation(version, service, operation);
+    const approved = options.change || interactive(options) && await selectOne('Submit this operation to the managed synthetic tool?', [
+        { value: false, label: 'Cancel' }, { value: true, label: 'Submit operation', detail: 'Selected arguments leave this device. Do not include real credentials.' },
+    ], options.signal);
+    if (!approved)
+        throw new CliError('tool_data_consent_required', 'Nothing was submitted. Use --approve-tool-change for explicit automated submission.', 2);
+    const data = await argumentsFile(options.file, options.signal);
+    const key = identifier(options.request ?? randomUUID());
+    output('tool_operation_intent', { instance_id: instance, request_key: key }, `Request: ${key}\nIf interrupted, use tools result ${instance} ${key}. Do not create a replacement request.`);
+    let command;
+    try {
+        command = await api(`${path}/commands`, { ...auth, method: 'POST', idempotencyKey: key,
+            bodyJson: `{"service_key":${JSON.stringify(service)},"operation_name":${JSON.stringify(operation)},"arguments":${data},"data_transfer_consent":true}` });
+        toolCommandRead(command, toolCommandMatches(command, commandScope, { key, service, operation }));
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError('tool_operation_acceptance_unconfirmed', `Operation acceptance is unconfirmed. Nothing was repeated. Inspect tools result ${instance} ${key} --workspace ${scope.workspace}.`);
+    }
+    const original = await api(`${path}/requests/${key}`, auth);
+    toolCommandRead(original, toolCommandMatches(original, commandScope, { key, id: command.id, digest: command.request_digest, service, operation }));
+    output('tool_operation_request', original, commandText(original));
+}

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

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

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

@@ -0,0 +1,30 @@
+import { api } from './auth.js';
+import { identifier } from './world-contracts.js';
+import { toolLifecycleRead, toolInstancePageMatches, toolInstanceDetailMatches, toolStartReceiptMatches, toolRemovalMatches } from './tool-lifecycle-contracts.js';
+export function toolLifecycleReads(scope, signal) {
+    const prefix = `/api/workspaces/${scope.workspace}/tools`, auth = { actor: scope.owner, workspace: scope.workspace, signal };
+    const owner = { actor: scope.owner, workspace: scope.workspace };
+    return {
+        async instances(page = 1, query = '', state = 'all') {
+            const value = await api(`${prefix}/instances?page=${page}&q=${encodeURIComponent(query)}&state=${encodeURIComponent(state)}`, auth);
+            return toolLifecycleRead(value, toolInstancePageMatches(value, scope.workspace, query, state, page));
+        },
+        async instance(id) {
+            const value = await api(`${prefix}/instances/${identifier(id)}`, auth);
+            return toolLifecycleRead(value, toolInstanceDetailMatches(value, scope.workspace, { id }));
+        },
+        async startRequest(key, selected = {}) {
+            const value = await api(`${prefix}/instance-requests/${identifier(key)}`, auth);
+            return toolLifecycleRead(value, toolInstanceDetailMatches(value, scope.workspace, { key, id: selected.id, actor: scope.owner })
+                && (!selected.input || await toolStartReceiptMatches(value, owner, key, selected.input)));
+        },
+        async removal(instance) {
+            const value = await api(`${prefix}/instances/${identifier(instance)}/removal`, auth);
+            return toolLifecycleRead(value, toolRemovalMatches(value, owner, { instance }));
+        },
+        async removalRequest(key, selected = {}) {
+            const value = await api(`${prefix}/removal-requests/${identifier(key)}`, auth);
+            return toolLifecycleRead(value, toolRemovalMatches(value, owner, { key, ...selected }));
+        },
+    };
+}