firedrill-run 2.2.4 → 3.0.0

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

@@ -0,0 +1,323 @@
+import { APP_ORIGIN } from './http.js';
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { api, openBrowser } from './auth.js';
+import { privateDirectory } from './credentials.js';
+import { CliError } from './http.js';
+import { selectMany, selectOne } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { selectedWorkspace } from './world-access.js';
+import { packageReads } from './tool-package-reads.js';
+import { toolLifecycleReads } from './tool-lifecycle-reads.js';
+import { toolConnectionReads } from './tool-connection-reads.js';
+import { allocationApproval } from './tool-runtime.js';
+import { datasetReads } from './dataset-reads.js';
+import { toolConnectionRead, toolConnectionMatches, toolConnectionAccepted, toolConnectionTokenMatches } from './tool-connection-contracts.js';
+import { toolLifecycleRead, toolInstanceDetailMatches, toolStartReceiptMatches, toolRemovalMatches } from './tool-lifecycle-contracts.js';
+const tty = (options) => !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+const pair = (one) => JSON.stringify([one.service_key, one.operation_name]);
+const removalText = (row) => `Instance: ${row.instance_id}\nRemoval request: ${row.request_key}\n`
+    + (row.completed_at ? `Removed ${row.completed_at}.` : `Removal requested ${row.requested_at}. Original cleanup is not yet confirmed.`)
+    + '\nActivity and saved data follow workspace retention. Removal is not data erasure.';
+async function permissionFile(path, signal) {
+    const filename = resolve(path), before = await lstat(filename);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > 1024 * 1024)
+        throw new CliError('tool_permissions_invalid', 'Choose a regular connection-permissions 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 size = 0;
+        for await (const chunk of file.createReadStream({ autoClose: false })) {
+            signal.throwIfAborted();
+            size += chunk.length;
+            if (size > 1024 * 1024)
+                throw new Error();
+            chunks.push(Buffer.from(chunk));
+        }
+        const raw = Buffer.concat(chunks).toString('utf8'), after = await file.stat();
+        if (size !== held.size || after.size !== held.size || after.mtimeMs !== held.mtimeMs || after.ctimeMs !== held.ctimeMs)
+            throw new Error();
+        const value = JSON.parse(raw);
+        if (!value || Object.keys(value).sort().join(',') !== 'duration_seconds,operations,protocols' || !Array.isArray(value.operations)
+            || !value.operations.length || !value.operations.every(one => one && Object.keys(one).sort().join(',') === 'operation_name,service_key'
+            && typeof one.service_key === 'string' && /^[a-z][a-z0-9_-]{0,79}$/.test(one.service_key)
+            && typeof one.operation_name === 'string' && /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/.test(one.operation_name))
+            || !Array.isArray(value.protocols) || !value.protocols.length || value.protocols.some(one => !['mcp', 'http'].includes(one))
+            || new Set(value.protocols).size !== value.protocols.length || !Number.isSafeInteger(value.duration_seconds) || value.duration_seconds < 60)
+            throw new Error();
+        return value;
+    }
+    catch {
+        throw new CliError('tool_permissions_invalid', 'Provide operations, protocols and duration_seconds only. No connection was requested.', 2);
+    }
+    finally {
+        await file.close();
+    }
+}
+async function choose(path, title, describe, auth, signal, 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.flatMap(one => { const label = describe(one); return label === null ? [] : [{ value: one.id, label }]; }),
+            ...(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', 'Nothing was requested.', 130);
+        if (value === '__next__')
+            page++;
+        else if (value === '__previous__')
+            page--;
+        else
+            return identifier(value);
+    }
+}
+export async function toolLifecycleCommand(args, options, output) {
+    const action = args[0], read = ['start-status', 'connection-request', 'connections', 'open', 'removal', 'remove-status'].includes(action);
+    if (args.length > (['start', 'disconnect', 'connection-request'].includes(action) ? 3 : 2) || options.upload || options.service !== undefined
+        || action !== 'connect' && options.file !== undefined || action !== 'connections' && options.page !== undefined
+        || !['connections', 'connect'].includes(action) && options.search !== undefined || !['start', 'connect', 'remove'].includes(action) && options.request !== undefined
+        || read && options.change || options.seconds !== undefined && action !== 'start'
+        || options.usageQuote !== undefined && action !== 'start'
+        || 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 [version] [dataset], start-status <request>, stop|remove|removal [instance], remove-status <request>, open [instance], connect [instance], connections [instance], connection-request <instance> <request>, or disconnect <instance> <connection>.', 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 lifecycle = toolLifecycleReads(scope, options.signal), owner = { workspace: scope.workspace, actor: scope.owner };
+    if (action === 'remove-status') {
+        const row = await lifecycle.removalRequest(identifier(args[1] ?? ''));
+        output('tool_removal', row, removalText(row));
+        return;
+    }
+    if (action === 'start-status') {
+        const row = await lifecycle.startRequest(identifier(args[1] ?? ''));
+        output('tool_instance', row, `${row.name} ${row.version}: ${row.state}\nInstance: ${row.id}${row.problem ? '\n' + row.problem : ''}`);
+        if (row.state === 'failed')
+            throw new CliError('tool_setup_failed', row.problem ?? 'This setup failed. No replacement was started.', 2);
+        return;
+    }
+    let id = args[1] ? identifier(args[1]) : undefined;
+    if (!id && tty(options))
+        id = action === 'start'
+            ? await choose(`${prefix}/catalog?state=inspected`, 'Tool version', one => one.state === 'inspected' ? `${one.name} ${one.version}` : null, auth, options.signal, packageReads(scope, options.signal).versions)
+            : await choose(`${prefix}/instances${['connect', 'stop'].includes(action) ? '?state=active' : ''}`, 'Tool instance', one => `${one.name} ${one.version} · ${one.state}`, auth, options.signal, page => lifecycle.instances(page, '', ['connect', 'stop'].includes(action) ? 'active' : 'all'));
+    if (!id)
+        throw new CliError('tool_selection_required', 'Provide a saved version for start or an instance ID for the other tool commands.', 2);
+    if (action === 'start') {
+        let dataset = args[2] ? identifier(args[2]) : null;
+        if (!dataset && tty(options)) {
+            const mode = await selectOne('Starting data', [{ value: 'packaged', label: 'Packaged data' }, { value: 'saved', label: 'Saved dataset' }], options.signal);
+            if (mode === 'saved')
+                dataset = await choose(`${prefix}/datasets?implementation_id=${id}&state=retained`, 'Saved dataset', row => row.available ? `${row.name} · version ${row.version}` : null, auth, options.signal, page => datasetReads(prefix, scope, options.signal).page({ page, implementation: id, state: 'retained' }));
+        }
+        const selected = dataset ? await datasetReads(prefix, scope, options.signal).detail(dataset, { implementation: id }) : null;
+        if (selected && (selected.kind !== 'tool' || !selected.available || selected.implementation_id !== id))
+            throw new CliError('tool_dataset_base_unavailable', 'Choose an available dataset for this exact tool version. No instance was requested.', 2);
+        const setup = await lifecycle.instances();
+        const 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 --seconds within the configured compute capacity.', 2);
+        const consent = options.change || tty(options) && await selectOne(`Start this isolated tool for ${duration} seconds using ${selected ? selected.name + ' version ' + selected.version : 'packaged data'}? The original instance stays unchanged.`, [{ value: false, label: 'Cancel' }, { value: true, label: 'Start instance' }], options.signal);
+        if (!consent)
+            throw new CliError('tool_start_consent_required', 'No instance was requested. Use --approve-tool-change for explicit automation consent.', 2);
+        const key = identifier(options.request ?? randomUUID());
+        const usageQuote = await allocationApproval(scope, options, { implementation_id: id, release_id: null, dataset_id: dataset,
+            restore: null, duration_seconds: duration, launch_request_key: key }, output);
+        output('tool_start_intent', { request_key: key, implementation_id: id, dataset_id: dataset }, `Setup request: ${key}\nIf interrupted, use tools start-status ${key}. Do not create a replacement request.`);
+        const input = { implementation_id: id, duration_seconds: duration, dataset_id: dataset, start_consent: true, usage_quote_id: usageQuote };
+        let row;
+        try {
+            const accepted = await api(`${prefix}/instances`, { ...auth, method: 'POST', idempotencyKey: key, body: input });
+            toolLifecycleRead(accepted, await toolStartReceiptMatches(accepted, owner, key, input));
+            row = await lifecycle.startRequest(key, { id: accepted.id, input });
+        }
+        catch {
+            try {
+                row = await lifecycle.startRequest(key, { input });
+            }
+            catch {
+                throw new CliError('tool_start_acceptance_unconfirmed', `Setup acceptance is unconfirmed. No replacement was submitted. Use tools start-status ${key} --workspace ${scope.workspace}.`);
+            }
+        }
+        output('tool_instance', row, `${row.name} ${row.version}: ${row.state}\nInstance: ${row.id}\nUse tools instance ${row.id} to inspect actual readiness.`);
+        return;
+    }
+    const path = `${prefix}/instances/${id}`;
+    const connections = toolConnectionReads(scope, id, options.signal), connectionScope = { ...owner, instance: id };
+    if (action === 'removal') {
+        const row = await lifecycle.removal(id);
+        output('tool_removal', row, removalText(row));
+        return;
+    }
+    if (action === 'remove') {
+        const original = await lifecycle.instance(id);
+        if (original.removal) {
+            if (options.request && original.removal.request_key !== identifier(options.request)) {
+                throw new CliError('tool_removal_pending', `This instance already has another removal. Use tools removal ${id}; no additional request was submitted.`, 2);
+            }
+            const row = await lifecycle.removal(id);
+            output('tool_removal', row, removalText(row));
+            return;
+        }
+        const approved = options.change || tty(options) && await selectOne(`Remove ${original.name} ${original.version}? Access closes and original compute stops. It moves to Removed history after cleanup. Saved activity/data follow workspace retention. Accepted operations may still finish.`, [{ value: false, label: 'Cancel' }, { value: true, label: 'Remove instance' }], options.signal);
+        if (!approved)
+            throw new CliError('tool_remove_consent_required', 'Nothing changed. Use --approve-tool-change for explicit automation consent.', 2);
+        const request = identifier(options.request ?? randomUUID());
+        output('tool_removal_intent', { instance_id: id, request_key: request }, `Removal request: ${request}\nIf interrupted, use tools remove-status ${request}. Do not invent a replacement request.`);
+        const row = await api(`${path}/removal`, { ...auth, method: 'POST', idempotencyKey: request,
+            body: { remove_consent: true, retain_saved_data: true } });
+        toolLifecycleRead(row, toolRemovalMatches(row, owner, { key: request, instance: id }));
+        const observed = await lifecycle.removalRequest(request, { instance: id, id: row.id });
+        output('tool_removal', observed, removalText(observed));
+        return;
+    }
+    if (action === 'open') {
+        const row = await lifecycle.instance(id);
+        const view = row.visual_interfaces.length ? 'interface' : 'activity';
+        const url = `${APP_ORIGIN}/tools/instances/${identifier(row.id)}?workspace=${encodeURIComponent(scope.workspace)}&view=${view}`;
+        const opened = options.openBrowser && !options.json ? await openBrowser(url) : false;
+        output('tool_browser_handoff', { workspace_id: scope.workspace, instance_id: row.id, view, url, opened }, (opened ? `Opened the tool ${view === 'interface' ? 'interface' : 'activity and history'} page. Browser consent and access stay in your signed-in portal.` : url)
+            + `\nUse workspace ${scope.workspace} in the browser.`);
+        return;
+    }
+    if (action === 'connections') {
+        const instance = await lifecycle.instance(id);
+        const result = await connections.page(Number(options.page ?? 1), options.search ?? '');
+        const quote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
+        output('tool_connections', result, (result.results.map(one => `${one.id} · ${one.protocols.join(', ')}\n${one.revoked_at ? 'Revoked'
+            : instance.removal || instance.terminal_at || instance.state === 'closing' || Date.parse(one.expires_at) <= Date.now() ? 'Ended' : 'Expires ' + one.expires_at}`).join('\n\n') || 'No connections in this instance.')
+            + `\nPage ${result.page}; ${result.count} connections.${result.next ? `\nNext: firedrill tools connections ${id} --workspace ${scope.workspace} --page ${result.page + 1}${options.search ? ' --search ' + quote(options.search) : ''}` : ''}`);
+        return;
+    }
+    if (action === 'connection-request') {
+        const row = await connections.original(identifier(args[2] ?? ''));
+        output('tool_connection', row, `Connection: ${row.id}\n${row.revoked_at ? 'Revoked.' : 'The token is not recoverable from this response. Use the saved private file, or revoke this connection before creating a replacement.'}`);
+        return;
+    }
+    if (action === 'stop' || action === 'disconnect') {
+        let grant = action === 'disconnect' && args[2] ? identifier(args[2]) : null;
+        if (action === 'disconnect' && !grant && tty(options))
+            grant = await choose(`${path}/connections`, 'Connection to revoke', one => `${one.protocols.join(', ')} · ${one.id}`, auth, options.signal, page => connections.page(page));
+        if (action === 'disconnect' && !grant)
+            throw new CliError('tool_connection_required', 'Choose a connection from tools connections.', 2);
+        const approved = options.change || tty(options) && await selectOne(action === 'stop' ? 'Close connections and stop this tool instance?' : 'Revoke this connection? An accepted operation may still finish.', [{ value: false, label: 'Cancel' }, { value: true, label: action === 'stop' ? 'Stop instance' : 'Revoke connection' }], options.signal);
+        if (!approved)
+            throw new CliError('tool_change_consent_required', 'Nothing changed. Use --approve-tool-change for explicit automation consent.', 2);
+        if (grant) {
+            const row = await api(`${path}/connections/${grant}`, { ...auth, method: 'DELETE' });
+            toolConnectionRead(row, toolConnectionMatches(row, connectionScope, { id: grant, revoked: true }));
+            output('tool_connection', row, 'Connection revoked. Any saved credential copies no longer authorize calls.');
+        }
+        else {
+            const original = await lifecycle.instance(id);
+            const accepted = await api(`${path}/stop`, { ...auth, method: 'POST', body: { stop_consent: true } });
+            toolLifecycleRead(accepted, toolInstanceDetailMatches(accepted, scope.workspace, { id }) && accepted.request_digest === original.request_digest);
+            const observed = await lifecycle.instance(id);
+            toolLifecycleRead(observed, observed.request_digest === original.request_digest && (!!observed.terminal_at || observed.state === 'closing'));
+            output('tool_instance', observed, observed.terminal_at ? 'Instance stopped.' : 'Stop requested. Inspect the instance for observed termination.');
+        }
+        return;
+    }
+    const selectedInstance = await lifecycle.instance(id);
+    if (!selectedInstance.observation_current)
+        throw new CliError('tool_instance_not_ready', 'Wait for a current instance observation before creating a connection.', 2);
+    let permission;
+    if (options.file)
+        permission = await permissionFile(options.file, options.signal);
+    else {
+        if (!tty(options))
+            throw new CliError('tool_permissions_required', 'Provide --file permissions.json with operations, protocols and duration_seconds. No credentials belong in that file.', 2);
+        let page = 1, selected = new Map(), duration = 0;
+        while (true) {
+            const choices = await connections.options(page, options.search ?? '', selectedInstance.state_epoch);
+            duration = choices.duration_seconds;
+            if (!choices.results.length && !selected.size)
+                throw new CliError('tool_operations_unavailable', 'No supported operations matched. No connection was requested.', 2);
+            const items = await selectMany('Allowed tool operations', choices.results.map(one => ({ value: pair(one), label: `${one.service_name}: ${one.operation_name}`, detail: one.effect === 'read' ? 'Read operation' : 'May change state' })), options.signal, choices.results.filter(one => selected.has(pair(one))).map(pair));
+            for (const one of choices.results) {
+                if (items.includes(pair(one)))
+                    selected.set(pair(one), { service_key: one.service_key, operation_name: one.operation_name });
+                else
+                    selected.delete(pair(one));
+            }
+            const next = await selectOne(`${selected.size} operations selected`, [{ value: 'done', label: 'Continue' },
+                ...(choices.next ? [{ value: 'next', label: 'Next page' }] : []), ...(page > 1 ? [{ value: 'previous', label: 'Previous page' }] : []), { value: 'cancel', label: 'Cancel' }], options.signal);
+            if (next === 'cancel')
+                throw new CliError('canceled', 'No connection was requested.', 130);
+            if (next === 'next')
+                page++;
+            else if (next === 'previous')
+                page--;
+            else
+                break;
+        }
+        const protocols = await selectMany('Connection access', [{ value: 'mcp', label: 'MCP' }, { value: 'http', label: 'HTTP' }], options.signal, ['mcp']);
+        permission = { operations: [...selected.values()], protocols, duration_seconds: duration };
+    }
+    if (!permission.operations.length || !permission.protocols.length || permission.duration_seconds < 60)
+        throw new CliError('tool_permissions_required', 'Select operations and a protocol while the tool has at least one minute remaining.', 2);
+    const consent = options.change || tty(options) && await selectOne('Create this connection and save its one-time credentials in a private local file?', [{ value: false, label: 'Cancel' }, { value: true, label: 'Create connection', detail: 'The file contains a scoped token. Never commit or share it publicly.' }], options.signal);
+    if (!consent)
+        throw new CliError('tool_change_consent_required', 'No connection was requested. Use --approve-tool-change for explicit automation consent.', 2);
+    // POSIX owner/mode guarantees are required before issuance. A Windows ACL
+    // export adapter is not silently replaced with an unprotected plaintext file.
+    if (!process.getuid || process.platform === 'win32')
+        throw new CliError('tool_private_file_unsupported', 'Use the browser Connections tab on this OS. Secure native credential-file delivery is not available.', 2);
+    const key = identifier(options.request ?? randomUUID()), directory = await privateDirectory();
+    const filename = join(directory, `tool-connection-${key}.json`);
+    let file;
+    try {
+        file = await open(filename, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+    }
+    catch {
+        throw new CliError('tool_private_file_unavailable', 'The private request file already exists or cannot be created. Inspect the original connection request; no new grant was issued.', 2);
+    }
+    try {
+        const held = await file.stat();
+        if (!held.isFile() || held.uid !== process.getuid() || held.nlink !== 1 || (held.mode & 0o777) !== 0o600)
+            throw new CliError('tool_private_file_unsafe', 'Private file ownership could not be established. No connection was requested.', 2);
+        await file.writeFile(JSON.stringify({ schema: 'firedrill.tool-connection-intent.v1', request_key: key, workspace_id: scope.workspace, instance_id: id }) + '\n');
+        await file.sync();
+        output('tool_connection_intent', { instance_id: id, request_key: key }, `Connection request: ${key}\nIf interrupted, use tools connection-request ${id} ${key}. No token is printed or retried.`);
+        const issued = await api(`${path}/connections`, { ...auth, method: 'POST', idempotencyKey: key, body: { ...permission, data_transfer_consent: true } });
+        toolConnectionRead(issued, await toolConnectionAccepted(issued, { ...connectionScope, epoch: selectedInstance.state_epoch }, key, permission) && toolConnectionTokenMatches(issued));
+        const recorded = await connections.original(key, { id: issued.id, digest: issued.request_digest, input: permission });
+        if (!issued.token_available_once || !issued.token || recorded.revoked_at || Date.parse(recorded.expires_at) <= Date.now())
+            throw new CliError('tool_token_unavailable', 'The one-time token was not delivered or its access has ended. Inspect and revoke the original connection before creating a replacement.');
+        const configuration = { schema: 'firedrill.tool-connection.v1', workspace_id: scope.workspace, instance_id: id, grant_id: issued.id, expires_at: issued.expires_at,
+            http: issued.http_url ? { operations_url: issued.http_url, headers: { Authorization: 'Bearer ' + issued.token, 'Content-Type': 'application/json' },
+                request: { method: 'POST', path: '/{service_key}/{operation_name}', body: { arguments: {} }, idempotency_header: 'Idempotency-Key' },
+                request_status_url: issued.http_url.replace(/\/operations$/, '/requests/{request_id}'),
+                ...(issued.http_services.length ? { native_routes: { services: issued.http_services, headers: { Authorization: 'Bearer ' + issued.token },
+                        idempotency_header: 'Idempotency-Key', idempotency_value: 'Use a UUID unless the route declares declared_vendor_key; that route accepts a non-secret visible ASCII key up to 255 characters.',
+                        request_status_url: issued.http_result_url, recovery: 'Reuse only the same original key and arguments. Firedrill-Request-Id returns the retained UUID for request_status_url. Unknown effects are never replayed.' } } : {}) } : null,
+            mcpServers: issued.mcp_url ? { synthetic_tool: { type: 'http', url: issued.mcp_url, headers: { Authorization: 'Bearer ' + issued.token } } } : {} };
+        const raw = Buffer.from(JSON.stringify(configuration, null, 2) + '\n');
+        try {
+            await file.truncate(0);
+            let offset = 0;
+            while (offset < raw.length) {
+                const written = await file.write(raw, offset, raw.length - offset, offset);
+                if (written.bytesWritten <= 0)
+                    throw new Error();
+                offset += written.bytesWritten;
+            }
+            await file.sync();
+        }
+        catch {
+            // Best effort only for this newly minted grant. Never claim revocation
+            // if the API reply was lost; its exact ID remains in workspace history.
+            await api(`${path}/connections/${issued.id}`, { ...auth, method: 'DELETE' }).catch(() => undefined);
+            throw new CliError('tool_credential_delivery_failed', 'Credential-file delivery failed. Inspect and revoke the original connection before creating a replacement.');
+        }
+        output('tool_connection_saved', { id: issued.id, instance_id: id, expires_at: issued.expires_at, credentials_file: filename }, `Connection created. Private configuration: ${filename}\nExpires: ${issued.expires_at}\nDo not commit this file or print its contents in CI logs.`);
+    }
+    finally {
+        await file.close();
+    }
+}

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

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

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

@@ -0,0 +1,41 @@
+import { api } from './auth.js';
+import { identifier } from './world-contracts.js';
+import { packageRead, toolVersionMatches, toolVersionPageMatches, toolServicesMatch, toolServiceMatches, toolOperationsMatch, toolOperationMatches, toolPackageMatches, toolPackagePageMatches } from './tool-package-contracts.js';
+export function packageReads(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 versions(page = 1, query = '', state = 'inspected') {
+            const value = await api(`${prefix}/catalog?page=${page}&q=${encodeURIComponent(query)}&state=${encodeURIComponent(state)}`, auth);
+            return packageRead(value, toolVersionPageMatches(value, scope.workspace, { page, query, state }));
+        },
+        async version(id) {
+            const value = await api(`${prefix}/implementations/${identifier(id)}?summary=true`, auth);
+            return packageRead(value, toolVersionMatches(value, scope.workspace, id));
+        },
+        async services(version, page = 1, query = '') {
+            const value = await api(`${prefix}/implementations/${version.id}/services?page=${page}&q=${encodeURIComponent(query)}`, auth);
+            return packageRead(value, toolServicesMatch(value, version, query, page));
+        },
+        async service(version, key) {
+            const value = await api(`${prefix}/implementations/${version.id}/services/${encodeURIComponent(key)}`, auth);
+            return packageRead(value, toolServiceMatches(value, version, key));
+        },
+        async operations(version, service, page = 1, query = '') {
+            const value = await api(`${prefix}/implementations/${version.id}/services/${encodeURIComponent(service)}/operations?page=${page}&q=${encodeURIComponent(query)}`, auth);
+            return packageRead(value, toolOperationsMatch(value, version, service, query, page));
+        },
+        async operation(version, service, name) {
+            const value = await api(`${prefix}/implementations/${version.id}/services/${encodeURIComponent(service)}/operations/${encodeURIComponent(name)}`, auth);
+            return packageRead(value, toolOperationMatches(value, version, service, name));
+        },
+        async request(key, selected = {}) {
+            const value = await api(`${prefix}/package-requests/${identifier(key)}`, auth);
+            return packageRead(value, toolPackageMatches(value, owner, { key, ...selected }));
+        },
+        async requests(page = 1, query = '', state = 'all') {
+            const value = await api(`${prefix}/package-requests?page=${page}&q=${encodeURIComponent(query)}&state=${encodeURIComponent(state)}`, auth);
+            return packageRead(value, toolPackagePageMatches(value, owner, query, state, page));
+        },
+    };
+}

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

@@ -0,0 +1,53 @@
+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 { readSavedRecords } from './saved-records.js';
+import { toolLifecycleReads } from './tool-lifecycle-reads.js';
+import { toolStateReads } from './tool-state-reads.js';
+const interactive = (options) => !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+const plain = (value) => JSON.stringify(value).slice(1, -1).replace(/[\u007f-\u009f]/g, character => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+async function choose(path, title, auth, signal, choices, read) {
+    let page = 1;
+    while (true) {
+        const response = read ? await read(page) : await api(`${path}?page=${page}`, auth);
+        const value = await selectOne(title, [
+            ...response.results.map(choices).filter((one) => one !== null).map(one => ({ value: one.id, label: one.label })),
+            ...(response.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', 'Record inspection canceled. No tool state changed.', 130);
+        if (value === '__next__')
+            page++;
+        else if (value === '__previous__')
+            page--;
+        else
+            return value;
+    }
+}
+export async function toolRecordsCommand(args, options, output) {
+    if (args.length > 5 || options.file !== undefined || options.upload || options.service !== undefined
+        || options.seconds !== undefined || options.change || options.request !== undefined
+        || args[4] !== undefined && (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 data [instance] [checkpoint] [collection] [row-position], with --page/--search for lists or --json.', 2);
+    }
+    const scope = await selectedWorkspace({ ...options, interactive: interactive(options) });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal, maximumResponseBytes: 16 * 1024 * 1024 };
+    const prefix = `/api/workspaces/${scope.workspace}/tools/instances`;
+    let instance = args[1], checkpoint = args[2], collection = args[3];
+    if (!instance && interactive(options))
+        instance = await choose(prefix, 'Tool instance', auth, options.signal, one => ({ id: one.id, label: `${plain(one.name)} ${plain(one.version)}` }), page => toolLifecycleReads(scope, options.signal).instances(page));
+    if (!instance)
+        throw new CliError('tool_instance_required', 'Provide an instance from tools instances.', 2);
+    instance = identifier(instance);
+    if (!checkpoint && interactive(options))
+        checkpoint = await choose(`${prefix}/${instance}/checkpoints`, 'Saved tool data', auth, options.signal, one => one.records.available ? { id: one.id, label: `${one.kind} · ${one.captured_at}` } : null, page => toolStateReads(scope, instance, options.signal).checkpoints(page));
+    if (!checkpoint)
+        throw new CliError('tool_checkpoint_required', 'Provide a checkpoint with available record pages from tools checkpoints.', 2);
+    checkpoint = identifier(checkpoint);
+    return readSavedRecords(`${prefix}/${instance}/checkpoints/${checkpoint}`, checkpoint, collection, args[4], { ...auth, json: options.json, page: options.page, search: options.search }, `firedrill tools data ${instance} ${checkpoint} --workspace ${scope.workspace}`, output);
+}

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

@@ -0,0 +1,96 @@
+import { randomUUID } from 'node:crypto';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { selectedWorkspace } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { requestInput } from './request-input.js';
+import { toolLifecycleReads } from './tool-lifecycle-reads.js';
+import { toolExtensionMatches, toolExtensionPageMatches, toolRuntimeQuoteMatches } from './tool-lifecycle-contracts.js';
+import { toolAllocationQuoteMatches, allocationCredits } from '../../contracts/tool-runtime-billing-contracts.js';
+import { creditAmount } from './credit-format.js';
+const tty = (options) => !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+export async function allocationQuote(scope, options, selection) {
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    if (!options.usageQuote && !tty(options))
+        throw new CliError('billing_quote_required', 'First use tools quote --file selection.json, then provide its approved --usage-quote and the same --request-key launch key. No instance was started.', 2);
+    const quote = options.usageQuote
+        ? await api(`/api/workspaces/${scope.workspace}/billing/usage/quotes/${identifier(options.usageQuote)}`, auth)
+        : await api(`/api/workspaces/${scope.workspace}/tools/runtime-quotes`, { ...auth, method: 'POST', idempotencyKey: randomUUID(), body: selection });
+    if (!toolAllocationQuoteMatches(quote, scope.workspace, selection) || Date.parse(quote.expires_at) <= Date.now())
+        throw new CliError('billing_scope_mismatch', 'Review a current runtime quote for this exact launch request.', 2);
+    return quote;
+}
+export async function allocationApproval(scope, options, selection, output) {
+    const quote = await allocationQuote(scope, options, selection);
+    output('tool_runtime_quote', quote, `${allocationCredits(quote, 'estimated')} credits estimated. Maximum budget ${allocationCredits(quote)} credits. The estimate is reserved only after approval.`);
+    if (tty(options) && !await selectOne('Approve this runtime budget?', [{ value: false, label: 'Cancel' }, { value: true, label: 'Approve runtime' }], options.signal))
+        throw new CliError('canceled', 'No runtime was started.', 130);
+    return quote.id;
+}
+export async function toolRuntimeCommand(args, options, output) {
+    const action = args[0], paged = action === 'extensions', extending = action === 'extend', quoting = action === 'extension-quote';
+    if (args.length > (action === 'extension-status' ? 3 : 2) || options.search !== undefined || options.service !== undefined || options.upload
+        || options.file !== undefined && action !== 'quote' || options.page !== undefined && !paged || options.seconds !== undefined && !extending && !quoting
+        || options.request !== undefined && !extending && action !== 'quote' || options.usageQuote !== undefined && !extending
+        || options.change && !extending || options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page))
+        throw new CliError('arguments_invalid', 'Use tools quote --file selection.json, extension-quote|extend <instance> --seconds <duration>, extensions <instance>, or extension-status <instance> <request>.', 2);
+    const scope = await selectedWorkspace({ ...options, interactive: tty(options) }), auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const prefix = `/api/workspaces/${scope.workspace}/tools`;
+    if (action === 'quote') {
+        if (args.length !== 1 || !options.file)
+            throw new CliError('arguments_invalid', 'Use tools quote --file selection.json.', 2);
+        const selected = JSON.parse(await requestInput(options.file, options.signal));
+        const quote = await api(`${prefix}/runtime-quotes`, { ...auth, method: 'POST', idempotencyKey: identifier(options.request ?? randomUUID()), body: selected });
+        if (!toolAllocationQuoteMatches(quote, scope.workspace, selected))
+            throw new CliError('billing_scope_mismatch', 'The quote did not match this selection.', 2);
+        output('tool_runtime_quote', quote, `${allocationCredits(quote)} credits maximum. Launch request: ${selected.launch_request_key}\nUse --request-key ${selected.launch_request_key} and --usage-quote ${quote.id} when starting.`);
+        return;
+    }
+    const instance = identifier(args[1] ?? ''), base = `${prefix}/instances/${instance}`, identity = { workspace: scope.workspace, actor: scope.owner, instance };
+    if (paged) {
+        const page = Number(options.page ?? 1), value = await api(`${base}/extensions?page=${page}`, auth);
+        if (!toolExtensionPageMatches(value, identity, page))
+            throw new CliError('tool_extension_scope_invalid', 'The runtime history did not match this instance.', 2);
+        output('tool_runtime_history', value, value.results.map(one => `${one.request_key}  ${one.state} · ${one.confirmed_expires_at ?? one.requested_expires_at}${one.problem ? '\n' + one.problem : ''}`).join('\n')
+            + `\nPage ${page}; ${value.count} requests.${value.next ? `\nNext: tools extensions ${instance} --page ${page + 1}` : ''}`);
+        return;
+    }
+    if (action === 'extension-status') {
+        const key = identifier(args[2] ?? ''), value = await api(`${base}/extensions/${key}`, auth);
+        if (!toolExtensionMatches(value, identity, { key }))
+            throw new CliError('tool_extension_scope_invalid', 'The extension did not match the original request.', 2);
+        output('tool_runtime_extension', value, `${value.state}${value.problem ? '\n' + value.problem : ''}\n${value.confirmed_expires_at ?? value.requested_expires_at}`);
+        return;
+    }
+    const tool = await toolLifecycleReads(scope, options.signal).instance(instance);
+    if (!tool.lifetime.can_extend)
+        throw new CliError('tool_extension_not_ready', tool.lifetime.extension_problem ?? 'This instance cannot extend its runtime now.', 2);
+    const maximum = Math.max(0, Math.floor(tool.lifetime.maximum_extension_seconds - Math.max(0, (Date.parse(tool.expires_at) - Date.now()) / 1000)));
+    if (maximum < 60)
+        throw new CliError('tool_extension_not_ready', 'There is no additional runtime available in the current finite extension window.', 2);
+    const seconds = options.seconds === undefined && tty(options) ? await selectOne('Additional runtime', [
+        { value: 60, label: '1 minute' }, { value: 3600, label: '1 hour' }, { value: 86400, label: '1 day' }, { value: 604800, label: '7 days' }
+    ].filter(one => one.value <= maximum), options.signal) : Number(options.seconds);
+    if (!Number.isSafeInteger(seconds) || seconds < 60 || seconds > maximum)
+        throw new CliError('tool_duration_invalid', 'Choose --seconds within this instance’s available extension window.', 2);
+    const selected = { additional_seconds: seconds, idle_timeout_seconds: tool.lifetime.idle_timeout_seconds,
+        expected_expires_at: tool.expires_at, state_epoch: tool.state_epoch };
+    if (!options.usageQuote && !tty(options) && !quoting)
+        throw new CliError('billing_quote_required', 'Use extension-quote first and pass its approved --usage-quote with --approve-tool-change.', 2);
+    const quote = options.usageQuote ? await api(`/api/workspaces/${scope.workspace}/billing/usage/quotes/${identifier(options.usageQuote)}`, auth)
+        : await api(`${base}/extensions/quote`, { ...auth, method: 'POST', idempotencyKey: randomUUID(), body: selected });
+    if (!toolRuntimeQuoteMatches(quote, tool, selected) || Date.parse(quote.expires_at) <= Date.now())
+        throw new CliError('billing_scope_mismatch', 'Review a current quote for this exact extension.', 2);
+    output('tool_extension_quote', quote, `${creditAmount(quote.maximum_units, quote.credit_scale)} credits maximum. New deadline: ${String(quote.scope.requested_expires_at)}`);
+    if (quoting)
+        return;
+    if (!options.change && !(tty(options) && await selectOne('Approve this finite runtime extension?', [{ value: false, label: 'Cancel' }, { value: true, label: 'Extend runtime' }], options.signal)))
+        throw new CliError('tool_extension_consent_required', 'No extension was requested. Use --approve-tool-change for the selected budget.', 2);
+    const key = identifier(options.request ?? randomUUID()), input = { ...selected, extend_consent: true, usage_quote_id: quote.id };
+    output('tool_extension_intent', { instance_id: instance, request_key: key, input }, `Request: ${key}\nRecovery: tools extension-status ${instance} ${key}`);
+    const row = await api(`${base}/extensions`, { ...auth, method: 'POST', idempotencyKey: key, body: input });
+    if (!toolExtensionMatches(row, identity, { key, input }))
+        throw new CliError('tool_extension_acceptance_unconfirmed', 'Inspect the original extension request. Do not replace it.', 2);
+    output('tool_runtime_extension', row, `${row.state}\nInspect tools extension-status ${instance} ${key}. Existing connections keep their own expiry.`);
+}

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

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

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

@@ -0,0 +1,31 @@
+import { api } from './auth.js';
+import { identifier } from './world-contracts.js';
+import { toolStateRead, toolCaptureAccepted, toolTransitionAccepted, toolCheckpointsMatch, toolCapturesMatch, toolTransitionsMatch } from './tool-state-contracts.js';
+export function toolStateReads(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 };
+    const params = (page, query) => `page=${page}&q=${encodeURIComponent(query)}`;
+    return {
+        async checkpoints(page = 1, query = '') {
+            const value = await api(`${prefix}/checkpoints?${params(page, query)}`, auth);
+            return toolStateRead(value, toolCheckpointsMatch(value, scope, query, page));
+        },
+        async captures(page = 1, query = '') {
+            const value = await api(`${prefix}/capture-requests?${params(page, query)}`, auth);
+            return toolStateRead(value, toolCapturesMatch(value, scope, query, page));
+        },
+        async transitions(page = 1, query = '') {
+            const value = await api(`${prefix}/transitions?${params(page, query)}`, auth);
+            return toolStateRead(value, toolTransitionsMatch(value, scope, query, page));
+        },
+        async capture(key, selected = {}) {
+            const value = await api(`${prefix}/capture-requests/${identifier(key)}`, auth);
+            return toolStateRead(value, await toolCaptureAccepted(value, scope, { ...selected, key }));
+        },
+        async transition(key, selected = {}) {
+            const value = await api(`${prefix}/transitions/${identifier(key)}`, auth);
+            return toolStateRead(value, await toolTransitionAccepted(value, scope, { ...selected, key }));
+        },
+    };
+}