firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/simple/tool-reuse.js

@@ -0,0 +1,526 @@
+// `firedrill tools definitions [list] | show | recipients | grants | share |
+// share-request | withdraw-share-request | revoke | copy | copy-request |
+// withdraw-copy-request | copy-status | withdraw-copy | dependents`: reusing a
+// tool definition across workspaces of one organization.
+//
+// - Sharing grants one exact inspected tool version to another workspace, read
+//   only or read and copy. Only an administrator of the owner workspace shares,
+//   recovers or withdraws a sharing request, or revokes, and only after the
+//   human approves. A grant shares the definition only: never a running
+//   instance, session, state, credentials or runtime rights.
+// - Using a shared version always needs an exact private copy. The package is
+//   copied server-side into this workspace, then inspected here like any
+//   upload. A copy is usable only once that inspection accepted it with a new
+//   private tool version; "copied" alone is not ready. This is not a tool's
+//   state fork (`tools state fork`).
+// - Request keys are printed before anything is sent. The same key returns the
+//   original; a lost answer is read back or withdrawn, never sent under a new key.
+// Nothing here starts an instance, runs anything or spends anything.
+import { randomUUID } from 'node:crypto';
+import { CliError } from '../http.js';
+import { selectOne, terminalText } from '../prompts.js';
+import { selectedWorkspace } from '../world-access.js';
+import { errorCode, retryTransient } from '../native/control-plane.js';
+import { answerLost } from '../native/metadata-requests.js';
+import { checkCopy, copyStatus, copyToolDefinition, getToolCopy, getToolDefinition, listToolDefinitions, listToolDependents, listToolGrants, listToolRecipients, recoverToolCopy, recoverToolGrant, revokeToolGrant, shareToolDefinition, toolReuseId, withdrawToolCopy, withdrawToolCopyRequest, withdrawToolGrantRequest, } from '../native/tool-reuse.js';
+import { answeredRefusal } from '../native/world-reuse.js';
+/** `firedrill tools <TOOL_REUSE_VERB> ...` is this module's command group. */
+export const TOOL_REUSE_VERB = 'definitions';
+const RECOVER_MS = 15_000;
+/** `--kind` names: a copy is what root calls a definition fork. */
+const DEPENDENT_KINDS = { world: 'world', copy: 'fork' };
+const CMD = `firedrill tools ${TOOL_REUSE_VERB}`;
+const tty = (options) => !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+const scopeOf = (options) => selectedWorkspace({ workspace: options.workspace, signal: options.signal,
+    interactive: tty(options), openBrowser: options.openBrowser && !options.json });
+const sharedHere = (scope, row) => row.owner_workspace_id !== scope.workspace.toLowerCase();
+const rethrow = (error) => { throw error; };
+function pageNumber(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^[1-9][0-9]{0,6}$/.test(value))
+        throw new CliError('arguments_invalid', 'Use --page with a number of 1 or more.', 2);
+    return Number(value);
+}
+/** Who owns a tool version and what this workspace may do with it. */
+export function toolAccess(scope, row) {
+    const state = row.state === 'inspected' ? '' : `; ${row.state}, so it cannot be copied`;
+    if (sharedHere(scope, row)) {
+        return `shared from workspace ${row.owner_workspace_id}: ${row.can_fork ? 'read and copy privately' : 'read only'}${state}`;
+    }
+    return `owned by this workspace${state}`;
+}
+/** Why a tool version cannot be copied here, with the one step that changes that. */
+function uncopyableText(row) {
+    if (row.state !== 'inspected')
+        return `This tool version is ${row.state}, so it cannot be copied.`;
+    return `Workspace ${row.owner_workspace_id} shared this tool version read only, so it cannot be copied here. Ask its owner for read-and-copy access.`;
+}
+function definitionLine(scope, row) {
+    return `  ${row.id}  ${terminalText(row.name)} ${terminalText(row.version)} (${terminalText(row.key)})  ${toolAccess(scope, row)}`;
+}
+function grantLine(grant) {
+    return `  ${grant.id}  workspace ${grant.recipient_workspace_id}  ${grant.allow_use ? 'read and copy' : 'read only'}  `
+        + `shared ${terminalText(grant.created_at)}${grant.revoked_at ? `  revoked ${terminalText(grant.revoked_at)}` : ''}`;
+}
+function copyText(copy, lead) {
+    const status = copyStatus(copy);
+    return [
+        `${lead}: copy ${copy.id} of tool version ${copy.source_implementation_id}: ${status.text}.`,
+        `Pinned to archive ${copy.archive_sha256} and contract ${copy.contract_digest}. Nothing was started.`,
+        copy.cleanup_pending ? 'Its unused private package is still being cleaned up.' : null,
+        status.ready ? `Use private tool version ${copy.upload.implementation_id} like any tool version of this workspace.`
+            : copy.state === 'pending' || copy.state === 'copying' || copy.state === 'copied' ? `Check it again with: ${CMD} copy-status ${copy.id}` : null,
+        copy.state === 'pending' ? `Stop it while it is pending with: ${CMD} withdraw-copy ${copy.id}` : null,
+        `Request key (rerun with --request-key to replay): ${copy.request_key}`,
+    ].filter((line) => line !== null).join('\n');
+}
+/** Root answers 404 for a page past the last one; that is not a missing version. */
+const pastEnd = (page, otherwise) => (error) => {
+    if ((page ?? 1) > 1 && error instanceof CliError && error.httpStatus === 404) {
+        throw new CliError('page_not_found', `There is no page ${page}. Start again from --page 1.`, 2);
+    }
+    return otherwise(error);
+};
+/** Only an organization administrator shares, recovers or withdraws a sharing request, revokes or lists recipients. */
+const adminOnly = (error) => {
+    if (errorCode(error) === 'admin_required') {
+        throw new CliError('native_tool_admin_required', 'Only an administrator of this organization can share tool versions, recover or withdraw a '
+            + 'sharing request, revoke sharing or list recipient workspaces. Nothing was shared or changed.', 3, error instanceof CliError ? error.httpStatus : null);
+    }
+    throw error;
+};
+const notReadable = (error) => {
+    if (error instanceof CliError && error.httpStatus === 404) {
+        throw new CliError('native_tool_definition_not_found', `That is not an available tool version this workspace can read. Find them with ${CMD}.`, 2);
+    }
+    throw error;
+};
+/** Grants and sharing requests are reached only through the workspace that owns the version; any other gets 404. */
+const ownerOnly = (error) => {
+    if (errorCode(error) === 'admin_required')
+        return adminOnly(error);
+    if (error instanceof CliError && error.httpStatus === 404) {
+        throw new CliError('native_tool_definition_not_found', 'That is not an available tool version this workspace owns. Only the owner workspace lists '
+            + `a version's grants or shares it; find this workspace's versions with ${CMD}. A grant of a version that is no longer available can still be revoked: `
+            + `${CMD} revoke <tool-version-id> <grant-id>.`, 2);
+    }
+    throw error;
+};
+const notMine = (error) => {
+    if (error instanceof CliError && error.httpStatus === 404) {
+        throw new CliError('native_tool_copy_not_found', `That is not one of your tool copies in this workspace. List them with ${CMD} dependents <tool-version-id> --kind copy.`, 2);
+    }
+    throw error;
+};
+/** Root's original-grant read is administrator-only, so reading a fresh key confirms that before the human is asked. It changes nothing. */
+const confirmAdministrator = (scope, implementationId, signal) => recoverToolGrant(scope, { implementationId, requestKey: randomUUID(), signal }).catch(ownerOnly);
+async function approval(options, question, yes, no) {
+    if (options.approve === true)
+        return true;
+    if (!tty(options))
+        return false;
+    return selectOne(question, [{ value: false, label: 'Not now', detail: no }, { value: true, ...yes }], options.signal);
+}
+/** Each verb's arguments and flags, checked before anything is read or sent. */
+export function checkToolReuseArguments(args, options) {
+    const verb = args[0] ?? 'list';
+    const rest = args[0] === undefined ? [] : args.slice(1);
+    const takes = {
+        list: ['search', 'page'], show: [], recipients: ['search', 'page'], grants: ['page'], share: ['request', 'approve'], 'share-request': [],
+        'withdraw-share-request': ['approve'], revoke: ['approve'], copy: ['request', 'approve'], 'copy-request': [], 'withdraw-copy-request': ['approve'],
+        'copy-status': [], 'withdraw-copy': ['approve'], dependents: ['kind', 'page'],
+    };
+    const positionals = {
+        list: [], show: ['tool version id'], recipients: [], grants: ['tool version id'], share: ['tool version id', 'workspace id', 'access'],
+        'share-request': ['tool version id', 'request key'], 'withdraw-share-request': ['tool version id', 'request key'],
+        revoke: ['tool version id', 'grant id'], copy: ['tool version id'], 'copy-request': ['request key'], 'withdraw-copy-request': ['request key'],
+        'copy-status': ['copy id'], 'withdraw-copy': ['copy id'], dependents: ['tool version id'],
+    };
+    const flags = { json: null, signal: null, workspace: null, openBrowser: null, search: '--search',
+        page: '--page', kind: '--kind', request: '--request-key', approve: '--approve-tool-change' };
+    const usage = () => new CliError('arguments_invalid', `Use ${CMD} [--search <prefix>], ${CMD} show <tool-version-id>, ${CMD} recipients, `
+        + `${CMD} grants <tool-version-id>, ${CMD} share <tool-version-id> <workspace-id> read|use, ${CMD} share-request|withdraw-share-request `
+        + `<tool-version-id> <request-key>, ${CMD} revoke <tool-version-id> <grant-id>, ${CMD} copy <tool-version-id>, ${CMD} copy-request|`
+        + `withdraw-copy-request <request-key>, ${CMD} copy-status|withdraw-copy <copy-id> or ${CMD} dependents <tool-version-id> [--kind world|copy].`, 2);
+    if (!Object.hasOwn(takes, verb) || rest.length !== positionals[verb].length)
+        throw usage();
+    const extra = Object.keys(flags)
+        .filter((flag) => flags[flag] !== null && options[flag] !== undefined && options[flag] !== false && !takes[verb].includes(flag));
+    if (extra.length)
+        throw new CliError('arguments_invalid', `${CMD} ${verb} does not take ${extra.map((flag) => flags[flag]).join(', ')}.`, 2);
+    positionals[verb].forEach((label, index) => {
+        if (label === 'access') {
+            if (rest[index] !== 'read' && rest[index] !== 'use')
+                throw usage();
+        }
+        else
+            toolReuseId(rest[index], label);
+    });
+    if (options.request !== undefined)
+        toolReuseId(options.request, 'request key');
+    if (options.kind !== undefined && !Object.hasOwn(DEPENDENT_KINDS, options.kind)) {
+        throw new CliError('arguments_invalid', `Use --kind ${Object.keys(DEPENDENT_KINDS).join('|')} with ${CMD} dependents.`, 2);
+    }
+    if (options.search !== undefined && [...options.search].length > 120)
+        throw new CliError('arguments_invalid', 'Use a name prefix of up to 120 characters.', 2);
+    pageNumber(options.page);
+}
+/** `share <tool-version-id> <workspace-id> read|use [--request-key <key>] [--approve-tool-change]`. */
+async function share(scope, args, options, emit) {
+    const [, version, recipientArg, mode] = args;
+    const signal = options.signal;
+    const recipient = toolReuseId(recipientArg, 'workspace id');
+    if (recipient === scope.workspace.toLowerCase()) {
+        throw new CliError('arguments_invalid', 'Share with another workspace of this organization; this one already owns the tool. Nothing was sent.', 2);
+    }
+    const allowUse = mode === 'use';
+    const access = allowUse ? 'read and copy privately' : 'read only';
+    const requestKey = options.request === undefined ? randomUUID() : toolReuseId(options.request, 'request key');
+    const versionId = toolReuseId(version, 'tool version id');
+    // A grant already made under this key is shown, never made again. It is read
+    // before the version itself: after a lost answer the version may no longer be
+    // available, but its original grant still is.
+    const original = options.request === undefined ? null
+        : await recoverToolGrant(scope, { implementationId: versionId, requestKey, signal }).catch(ownerOnly);
+    if (original) {
+        if (original.recipient_workspace_id !== recipient || original.allow_use !== allowUse) {
+            throw new CliError('idempotency_conflict', `Request ${requestKey} shared this tool version with workspace ${original.recipient_workspace_id} `
+                + `(${original.allow_use ? 'read and copy' : 'read only'}). Nothing was changed; share differently under a new request key.`, 2);
+        }
+        emit('tool_definition_grant', original, `Already shared under request ${requestKey}:\n${grantLine(original)}`
+            + (original.revoked_at ? '\nThis grant was revoked. A request key is never renewed: to share again, start without --request-key.' : ''));
+        return;
+    }
+    const row = await getToolDefinition(scope, { implementationId: versionId, signal }).catch(notReadable);
+    const rerun = `${CMD} share ${row.id} ${recipient} ${mode} --request-key ${requestKey}`;
+    const read = `${CMD} share-request ${row.id} ${requestKey}`;
+    if (sharedHere(scope, row)) {
+        throw new CliError('native_tool_share_owner_only', `Only workspace ${row.owner_workspace_id}, which owns this tool version, can share it. Nothing was sent.`, 2);
+    }
+    // The original-request read is administrator-only, so it confirms that before
+    // the human is asked. A supplied key was already read above.
+    if (options.request === undefined)
+        await confirmAdministrator(scope, row.id, signal);
+    emit('tool_definition_share_review', { version: row, recipient_workspace_id: recipient, allow_use: allowUse, request_key: requestKey }, [
+        `Share tool ${terminalText(row.name)} ${terminalText(row.version)} (version ${row.id}) with workspace ${recipient}: ${access}.`,
+        allowUse ? 'It can read this exact definition and copy its package into a private version of its own, which is inspected there before use.'
+            : 'It can read this exact definition (services, operations and inspection), but not copy it.',
+        'Never shared: running instances, sessions, saved state, credentials or runtime rights. It can never edit this version.',
+        'Revoking later stops new reads and copies, including a copy still pending or copying; copies that finished copying stay its own.',
+        row.state === 'inspected' ? null : `This version is ${row.state}, so that workspace cannot copy it.`,
+    ].filter((line) => line !== null).join('\n'));
+    const approved = await approval(options, `Share this tool version with workspace ${recipient} (${access})?`, { label: 'Share it', detail: `Grants ${access} access to this exact definition only.` }, 'Nothing is shared.');
+    if (!approved)
+        throw new CliError('tool_share_consent_required', `Nothing was shared. After the human approves: ${rerun} --approve-tool-change`, 2);
+    if (options.json)
+        emit('request_prepared', { request_key: requestKey }, '');
+    else
+        process.stderr.write(`Request key: ${requestKey} (if interrupted, rerun ${rerun} --approve-tool-change; ${read} reads it back)\n`);
+    let grant;
+    try {
+        // The same key and body replay the original grant, so a retry never shares twice.
+        grant = await retryTransient(() => shareToolDefinition(scope, { implementationId: row.id, recipientWorkspaceId: recipient, allowUse, requestKey, signal }), { signal, attempts: 3 });
+    }
+    catch (error) {
+        if (errorCode(error) === 'admin_required')
+            adminOnly(error);
+        if (errorCode(error) === 'native_tool_definition_request_withdrawn') {
+            throw new CliError('native_tool_definition_request_withdrawn', `Sharing request ${requestKey} was withdrawn, so it will never land. Share again `
+                + 'without --request-key only if the human still wants it.', 2);
+        }
+        if (errorCode(error) === 'native_tool_definition_grant_exists') {
+            throw new CliError('native_tool_definition_grant_exists', `Workspace ${recipient} already has an active grant for this version. List it with `
+                + `${CMD} grants ${row.id}; to change its access, revoke it first. Nothing was shared.`, 2);
+        }
+        // A refusal with the service's own code wrote nothing; only an answer that never arrived is recovered by its key.
+        if (signal.aborted || !answerLost(error) || answeredRefusal(error)) {
+            if (error instanceof CliError && error.httpStatus === 404) {
+                throw new CliError('native_tool_recipient_unavailable', 'That workspace is not another active workspace of this organization, or this tool '
+                    + `version is no longer available. Find recipients with ${CMD} recipients. Nothing was shared.`, 2);
+            }
+            throw error;
+        }
+        const recovered = await recoverToolGrant(scope, { implementationId: row.id, requestKey, signal: AbortSignal.timeout(RECOVER_MS) }).catch(() => null);
+        if (!recovered) {
+            throw new CliError('native_tool_share_unconfirmed', `The share was not confirmed and may still land. Read it with ${read}, or rerun ${rerun} `
+                + '--approve-tool-change, which returns the original instead of sharing twice. Before sharing differently, withdraw it: '
+                + `${CMD} withdraw-share-request ${row.id} ${requestKey} --approve-tool-change. Never share it again under a new key.`);
+        }
+        if (recovered.recipient_workspace_id !== recipient || recovered.allow_use !== allowUse) {
+            throw new CliError('native_response_unconfirmed', `Request ${requestKey} recorded a different grant, not this share. Nothing else was sent. `
+                + `Read it with ${read}.`, 2);
+        }
+        grant = recovered;
+    }
+    emit('tool_definition_grant', grant, `Shared tool ${terminalText(row.name)} ${terminalText(row.version)} with workspace ${grant.recipient_workspace_id}: `
+        + `${grant.allow_use ? 'read and copy privately' : 'read only'}.\n${grantLine(grant)}\nRevoke it with ${CMD} revoke ${row.id} ${grant.id}`);
+}
+/** `withdraw-share-request <tool-version-id> <request-key> [--approve-tool-change]`. */
+async function withdrawShareRequest(scope, implementationId, requestKey, options, emit) {
+    const signal = options.signal;
+    const landed = (grant) => `This sharing request already landed, so nothing was withdrawn:\n${grantLine(grant)}\n`
+        + (grant.revoked_at ? 'It is already revoked.' : `Revoke it instead: ${CMD} revoke ${implementationId} ${grant.id} --approve-tool-change`);
+    const original = await recoverToolGrant(scope, { implementationId, requestKey, signal }).catch(ownerOnly);
+    if (original) {
+        emit('tool_definition_grant', original, landed(original));
+        return;
+    }
+    const approved = await approval(options, `Withdraw sharing request ${requestKey} so it can never land?`, { label: 'Withdraw', detail: 'If it already landed, the grant is shown instead and kept.' }, 'Nothing is changed.');
+    if (!approved) {
+        throw new CliError('tool_share_consent_required', `Nothing was withdrawn. After the human approves: ${CMD} withdraw-share-request ${implementationId} `
+            + `${requestKey} --approve-tool-change`, 2);
+    }
+    const outcome = await retryTransient(() => withdrawToolGrantRequest(scope, { implementationId, requestKey, signal }), { signal, attempts: 3 })
+        .catch(ownerOnly);
+    if (outcome.state === 'committed') {
+        emit('tool_definition_grant', outcome.receipt, landed(outcome.receipt));
+        return;
+    }
+    emit('tool_definition_share_withdrawal', { state: 'withdrawn', implementation_id: implementationId, request_key: requestKey }, `Withdrawn. Sharing request ${requestKey} will never land. Share again without --request-key only if the human still wants it.`);
+}
+/** `revoke <tool-version-id> <grant-id> [--approve-tool-change]`. */
+async function revoke(scope, implementationId, grantId, options, emit) {
+    const signal = options.signal;
+    const missing = () => new CliError('native_tool_grant_not_found', 'That is not a sharing grant of a tool version this workspace owns. Nothing was '
+        + `changed. List them with ${CMD} grants ${implementationId}.`, 2);
+    // Revoked by its exact id: root's revoke needs no listing (which also skips
+    // versions no longer available), and grant history is never searched.
+    await confirmAdministrator(scope, implementationId, signal);
+    const approved = await approval(options, `Revoke sharing grant ${grantId} of tool version ${implementationId}?`, { label: 'Revoke', detail: 'Stops that workspace\'s new reads and copies, including a copy still pending or copying. '
+            + 'Copies that finished copying are its own and are not removed.' }, 'Nothing is changed.');
+    if (!approved) {
+        throw new CliError('tool_share_consent_required', `Nothing was changed. After the human approves: ${CMD} revoke ${implementationId} ${grantId} `
+            + '--approve-tool-change', 2);
+    }
+    const revoked = await retryTransient(() => revokeToolGrant(scope, { implementationId, grantId, signal }), { signal, attempts: 3 })
+        .catch((error) => {
+        if (error instanceof CliError && error.httpStatus === 404)
+            throw missing();
+        return ownerOnly(error);
+    });
+    // Idempotent: a grant revoked earlier is returned as it is, with its original revocation time.
+    emit('tool_definition_grant', revoked, `Grant ${revoked.id} is revoked (since ${terminalText(revoked.revoked_at)}).\n${grantLine(revoked)}\n`
+        + `Workspace ${revoked.recipient_workspace_id} can no longer read or copy this tool version, and a copy of it still pending or copying stops as rejected. `
+        + 'Copies that finished copying stay its own.');
+}
+/** `copy <tool-version-id> [--request-key <key>] [--approve-tool-change]`. */
+async function copy(scope, sourceId, options, emit) {
+    const signal = options.signal;
+    const requestKey = options.request === undefined ? randomUUID() : toolReuseId(options.request, 'request key');
+    // A copy already made under this key is shown, never made again. Root
+    // returns it before checking current access, so this works after a revoke.
+    if (options.request !== undefined) {
+        const original = await recoverToolCopy(scope, { requestKey, signal });
+        if (original) {
+            if (original.source_implementation_id !== sourceId) {
+                throw new CliError('idempotency_conflict', `Request ${requestKey} copied tool version ${original.source_implementation_id}, not ${sourceId}. `
+                    + 'Nothing was sent; copy this version without --request-key.', 2);
+            }
+            emit('tool_definition_copy', original, copyText(original, 'Already started under this request key'));
+            return;
+        }
+    }
+    const source = await getToolDefinition(scope, { implementationId: sourceId, signal }).catch(notReadable);
+    if (!source.can_fork)
+        throw new CliError('native_tool_copy_not_allowed', `${uncopyableText(source)} Nothing was sent.`, 2);
+    const rerun = `${CMD} copy ${source.id} --request-key ${requestKey}`;
+    emit('tool_definition_copy_review', { source, request_key: requestKey }, [
+        `Copy tool ${terminalText(source.name)} ${terminalText(source.version)} (version ${source.id}`
+            + `${sharedHere(scope, source) ? `, shared from workspace ${source.owner_workspace_id}` : ''}) into a private package of this workspace.`,
+        `The copy is exact: archive ${source.archive_sha256}, contract ${source.contract_digest}.`,
+        'This workspace then inspects it like any upload; only an accepted copy becomes a usable private tool version.',
+        'Nothing is started. No running instance, session, saved state, credentials or runtime rights come with it.',
+        // The copy worker re-checks the grant and the source until the package is copied.
+        'Once copied, later changes or a revoke at the source do not touch the copy. Until then, a revoke or the source becoming unavailable '
+            + 'stops it as rejected.',
+    ].join('\n'));
+    const approved = await approval(options, 'Copy this tool version into a private package of this workspace?', { label: 'Copy it', detail: 'Copies the exact package here, then inspects it.' }, 'Nothing is copied.');
+    if (!approved)
+        throw new CliError('tool_copy_consent_required', `Nothing was copied. After the human approves: ${rerun} --approve-tool-change`, 2);
+    if (options.json)
+        emit('request_prepared', { request_key: requestKey }, '');
+    else
+        process.stderr.write(`Request key: ${requestKey} (if interrupted, rerun ${rerun} --approve-tool-change; ${CMD} copy-request ${requestKey} reads it back)\n`);
+    let result;
+    try {
+        // The same key returns the original copy, so a retry never copies twice.
+        result = await retryTransient(() => copyToolDefinition(scope, { source, requestKey, signal }), { signal, attempts: 3 });
+    }
+    catch (error) {
+        if (errorCode(error) === 'native_tool_definition_request_withdrawn') {
+            throw new CliError('native_tool_definition_request_withdrawn', `Copy request ${requestKey} was withdrawn, so it will never land. Copy again without `
+                + '--request-key only if the human still wants it.', 2);
+        }
+        // A refusal with the service's own code wrote nothing; only an answer that never arrived is recovered by its key.
+        if (signal.aborted || !answerLost(error) || answeredRefusal(error)) {
+            if ((error instanceof CliError && error.httpStatus === 404) || errorCode(error) === 'native_tool_definition_unavailable') {
+                throw new CliError('native_tool_copy_unavailable', 'This tool version can no longer be copied here: its share was revoked or it is no longer '
+                    + 'available. Nothing was copied.', 2);
+            }
+            throw error;
+        }
+        const recovered = await recoverToolCopy(scope, { requestKey, signal: AbortSignal.timeout(RECOVER_MS) }).catch(() => null);
+        if (!recovered) {
+            throw new CliError('native_tool_copy_unconfirmed', `The copy was not confirmed and may still start (request ${requestKey}). Read it with `
+                + `${CMD} copy-request ${requestKey}, or rerun ${rerun} --approve-tool-change, which returns the original instead of copying twice. `
+                + `Before deciding differently, withdraw it: ${CMD} withdraw-copy-request ${requestKey} --approve-tool-change. Never copy it again under a new key.`);
+        }
+        result = checkCopy(recovered, { sourceId: source.id, archive: source.archive_sha256, contract: source.contract_digest, requestKey });
+    }
+    emit('tool_definition_copy', result, copyText(result, 'Copy started'));
+}
+/** `withdraw-copy-request <request-key> [--approve-tool-change]`: make an unanswered copy request unable to land. */
+async function withdrawCopyRequest(scope, requestKey, options, emit) {
+    const signal = options.signal;
+    const landed = (original) => copyText(original, 'This request already landed, so nothing was withdrawn');
+    const original = await recoverToolCopy(scope, { requestKey, signal });
+    if (original) {
+        emit('tool_definition_copy', original, landed(original));
+        return;
+    }
+    const approved = await approval(options, `Withdraw copy request ${requestKey} so it can never land?`, { label: 'Withdraw', detail: 'If it already landed, the copy is shown instead.' }, 'Nothing is changed.');
+    if (!approved) {
+        throw new CliError('tool_copy_consent_required', `Nothing was withdrawn. After the human approves: ${CMD} withdraw-copy-request ${requestKey} `
+            + '--approve-tool-change', 2);
+    }
+    const outcome = await retryTransient(() => withdrawToolCopyRequest(scope, { requestKey, signal }), { signal, attempts: 3 });
+    if (outcome.state === 'committed') {
+        emit('tool_definition_copy', outcome.receipt, landed(outcome.receipt));
+        return;
+    }
+    emit('tool_definition_copy_withdrawal', { state: 'withdrawn', request_key: requestKey }, `Withdrawn. Copy request ${requestKey} will never land. Copy again without --request-key only if the human still wants it.`);
+}
+/** `withdraw-copy <copy-id> [--approve-tool-change]`: stop one of your copies while it is still pending. */
+async function withdrawCopy(scope, copyId, options, emit) {
+    const signal = options.signal;
+    const current = await getToolCopy(scope, { copyId, signal }).catch(notMine);
+    if (current.state !== 'pending') {
+        emit('tool_definition_copy', current, copyText(current, current.state === 'withdrawn' ? 'Already withdrawn'
+            : 'Only a pending copy can be withdrawn, so nothing was sent'));
+        return;
+    }
+    const approved = await approval(options, `Withdraw copy ${copyId} before it starts?`, { label: 'Withdraw', detail: 'If copying already began, it is shown as it is instead.' }, 'Nothing is changed.');
+    if (!approved)
+        throw new CliError('tool_copy_consent_required', `Nothing was withdrawn. After the human approves: ${CMD} withdraw-copy ${copyId} --approve-tool-change`, 2);
+    const after = await retryTransient(() => withdrawToolCopy(scope, { copyId, signal }), { signal, attempts: 3 }).catch(notMine);
+    emit('tool_definition_copy', after, copyText(after, after.state === 'withdrawn' ? 'Withdrawn'
+        : 'Copying had already begun, so it was not withdrawn'));
+}
+/**
+ * `tools definitions [list] [--search <prefix>] [--page <n>] | show <id> | recipients | grants <id>
+ *  | share <id> <workspace-id> read|use | share-request|withdraw-share-request <id> <key> | revoke <id> <grant-id>
+ *  | copy <id> | copy-request|withdraw-copy-request <key> | copy-status|withdraw-copy <copy-id> | dependents <id> [--kind world|copy]`.
+ * Sharing, revoking, copying and withdrawing need --approve-tool-change (or a prompt); keyed writes take --request-key.
+ */
+export async function toolReuseCommand(args, options, emit) {
+    checkToolReuseArguments(args, options);
+    const [verb = 'list', first, second] = args;
+    const signal = options.signal;
+    const scope = await scopeOf(options);
+    if (verb === 'share')
+        return share(scope, args, options, emit);
+    if (verb === 'withdraw-share-request')
+        return withdrawShareRequest(scope, toolReuseId(first, 'tool version id'), toolReuseId(second, 'request key'), options, emit);
+    if (verb === 'revoke')
+        return revoke(scope, toolReuseId(first, 'tool version id'), toolReuseId(second, 'grant id'), options, emit);
+    if (verb === 'copy')
+        return copy(scope, toolReuseId(first, 'tool version id'), options, emit);
+    if (verb === 'withdraw-copy-request')
+        return withdrawCopyRequest(scope, toolReuseId(first, 'request key'), options, emit);
+    if (verb === 'withdraw-copy')
+        return withdrawCopy(scope, toolReuseId(first, 'copy id'), options, emit);
+    if (verb === 'list') {
+        const number = pageNumber(options.page);
+        const page = await listToolDefinitions(scope, { search: options.search, page: number, signal }).catch(pastEnd(number, rethrow));
+        emit('tool_definitions', page, [
+            `Tool versions this workspace can read, newest first, page ${page.page} (${page.count} in all):`,
+            ...page.results.map((row) => definitionLine(scope, row)),
+            page.results.length ? null : '  none',
+            page.next ? `More: --page ${page.page + 1}` : null,
+            `Read one: ${CMD} show <tool-version-id>. Copy a shared one privately: ${CMD} copy <tool-version-id>`,
+        ].filter((line) => line !== null).join('\n'));
+        return;
+    }
+    if (verb === 'show') {
+        const row = await getToolDefinition(scope, { implementationId: toolReuseId(first, 'tool version id'), signal }).catch(notReadable);
+        emit('tool_definition', row, [
+            `Tool ${terminalText(row.name)} ${terminalText(row.version)} (${terminalText(row.key)}): version ${row.id}`,
+            row.description ? terminalText(row.description) : null,
+            `Access: ${toolAccess(scope, row)}`,
+            `State: ${row.state}${row.inspected_at ? `, inspected ${terminalText(row.inspected_at)}` : ''}${row.revoked_at ? `, revoked ${terminalText(row.revoked_at)}` : ''}`,
+            `Archive ${row.archive_sha256}  contract ${row.contract_digest}`,
+            `Interfaces: ${row.interfaces.length ? row.interfaces.map(terminalText).join(', ') : 'none declared'}`,
+            'Services:',
+            ...(row.services ?? []).map((one) => `  ${terminalText(one.key)}  ${terminalText(one.name)}  ${one.operation_count} operation(s)`
+                + `${one.visual_interface_declared ? '  visual interface declared' : ''}`),
+            row.can_fork && sharedHere(scope, row) ? `Copy it privately: ${CMD} copy ${row.id}` : null,
+            sharedHere(scope, row) ? null : `Share it: ${CMD} share ${row.id} <workspace-id> read|use`,
+        ].filter((line) => line !== null).join('\n'));
+        return;
+    }
+    if (verb === 'recipients') {
+        const number = pageNumber(options.page);
+        const page = await listToolRecipients(scope, { search: options.search, page: number, signal }).catch(pastEnd(number, adminOnly));
+        emit('tool_definition_recipients', page, [
+            `Workspaces of this organization a tool version can be shared with, page ${page.page} (${page.count} in all):`,
+            ...page.results.map((one) => `  ${one.id}  ${terminalText(one.name)}`),
+            page.results.length ? null : '  none',
+            page.next ? `More: --page ${page.page + 1}` : null,
+            `Share a version: ${CMD} share <tool-version-id> <workspace-id> read|use`,
+        ].filter((line) => line !== null).join('\n'));
+        return;
+    }
+    if (verb === 'grants') {
+        const implementationId = toolReuseId(first, 'tool version id');
+        const number = pageNumber(options.page);
+        const page = await listToolGrants(scope, { implementationId, page: number, signal }).catch(pastEnd(number, ownerOnly));
+        emit('tool_definition_grants', { implementation_id: implementationId, ...page }, [
+            `Sharing grants of tool version ${implementationId}, page ${page.page} (${page.count} in all, revoked ones included):`,
+            ...page.results.map(grantLine),
+            page.results.length ? null : '  none',
+            page.next ? `More: --page ${page.page + 1}` : null,
+            `Share it: ${CMD} share ${implementationId} <workspace-id> read|use`,
+        ].filter((line) => line !== null).join('\n'));
+        return;
+    }
+    if (verb === 'share-request') {
+        const implementationId = toolReuseId(first, 'tool version id');
+        const requestKey = toolReuseId(second, 'request key');
+        const grant = await recoverToolGrant(scope, { implementationId, requestKey, signal }).catch(ownerOnly);
+        emit('tool_definition_grant', grant ?? { implementation_id: implementationId, request_key: requestKey, state: 'not_found' }, grant ? grantLine(grant).trim()
+            : `None of your sharing requests for this tool version is recorded under ${requestKey}. An unanswered request may still arrive. Rerun the `
+                + `original share with the same --request-key (it returns the original instead of sharing twice), or withdraw it first: `
+                + `${CMD} withdraw-share-request ${implementationId} ${requestKey}. Never share it under a new key.`);
+        return;
+    }
+    if (verb === 'copy-request') {
+        const requestKey = toolReuseId(first, 'request key');
+        const original = await recoverToolCopy(scope, { requestKey, signal });
+        emit('tool_definition_copy', original ?? { request_key: requestKey, state: 'not_found' }, original ? copyText(original, 'Copy')
+            : `None of your copy requests is recorded under ${requestKey}, or it was withdrawn. An unanswered request may still land. Rerun the original `
+                + `copy with --request-key ${requestKey} (it returns the original instead of copying twice), or withdraw it first: `
+                + `${CMD} withdraw-copy-request ${requestKey}. Never copy it again under a new key.`);
+        return;
+    }
+    if (verb === 'copy-status') {
+        const current = await getToolCopy(scope, { copyId: toolReuseId(first, 'copy id'), signal }).catch(notMine);
+        emit('tool_definition_copy', current, copyText(current, 'Copy'));
+        return;
+    }
+    const implementationId = toolReuseId(first, 'tool version id');
+    const kind = (options.kind ?? 'world');
+    const number = pageNumber(options.page);
+    const page = await listToolDependents(scope, { implementationId, kind: DEPENDENT_KINDS[kind], page: number, signal }).catch(pastEnd(number, notReadable));
+    emit('tool_definition_dependents', { implementation_id: implementationId, kind, ...page }, [
+        `${kind === 'world' ? 'World revisions in this workspace that use' : 'Your private copies of'} tool version ${implementationId}, `
+            + `page ${page.page} (${page.count} in all):`,
+        ...page.results.map((one) => 'world_id' in one
+            ? `  world ${one.world_id} revision ${one.revision} (${one.id})  ${terminalText(one.created_at)}`
+            : `  copy ${one.id}  ${copyStatus(one).text}  ${terminalText(one.created_at)}`),
+        page.results.length ? null : '  none',
+        page.next ? `More: --page ${page.page + 1}` : null,
+        'Other workspaces\' worlds and copies are never shown here.',
+        kind === 'world' ? `Your private copies of it: ${CMD} dependents ${implementationId} --kind copy` : null,
+    ].filter((line) => line !== null).join('\n'));
+}

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

@@ -0,0 +1,100 @@
+import { createHash } from 'node:crypto';
+import { api } from '../auth.js';
+import { CliError } from '../http.js';
+import { selectMany, selectOne, terminalText } from '../prompts.js';
+import { catalogRead, catalogPageMatches, catalogSetupMatches } from '../catalog-contracts.js';
+import { sleep } from '../native/control-plane.js';
+import { SETUP_MAX_SELECTIONS } from '../native/tool-setups.js';
+/** Stable child identity: retries of the same start/release never adopt twice. */
+function adoptionKey(start, release) {
+    const hex = createHash('sha256').update(`firedrill.start.catalog.v1:${start}:${release}`).digest('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+export async function chooseStartCatalog(scope, saved, options) {
+    const query = options.search ?? '';
+    if ([...query].length > 200)
+        throw new CliError('arguments_invalid', 'Use --search with at most 200 characters.', 2);
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const prefix = `/api/workspaces/${scope.workspace}/tools`;
+    const releases = [];
+    let more = false;
+    for (let page = 1; page <= 5; page++) {
+        const value = await api(`${prefix}/library?page=${page}&q=${encodeURIComponent(query)}&category=`, auth);
+        catalogRead(value, catalogPageMatches(value, scope.workspace, query, page, ''));
+        releases.push(...value.results.filter(row => row.available && row.saved_version?.state !== 'revoked'));
+        more = !!value.next;
+        if (!more)
+            break;
+    }
+    const savedIds = new Set(saved.map(row => row.implementation_id));
+    const choices = saved.map(row => ({
+        value: { kind: 'saved', id: row.implementation_id }, label: `${row.name} ${row.version}`,
+        detail: `Saved · ${row.services.map(service => service.service_key).join(', ')}`,
+    }));
+    for (const release of releases) {
+        if (release.saved_version && savedIds.has(release.saved_version.id))
+            continue;
+        choices.push({ value: { kind: 'catalog', release }, label: `${release.name} ${release.version}`,
+            detail: `Catalog · ${release.operation_count} operations${release.saved_version ? ' · saved version' : ' · save before review'}` });
+    }
+    if (!choices.length)
+        throw new CliError('tool_catalog_empty', 'No available tools match. Try tools start --search <name>, or upload your own tool package.', 2);
+    if (more)
+        process.stderr.write('Catalog is limited to five pages; use tools start --search <name> to narrow it.\n');
+    const selected = await selectMany(`Choose up to ${SETUP_MAX_SELECTIONS} tools (Space toggles, Enter confirms)`, choices, options.signal);
+    if (!selected.length || selected.length > SETUP_MAX_SELECTIONS)
+        throw new CliError('tool_selection_invalid', `Choose 1–${SETUP_MAX_SELECTIONS} tools. Nothing was started.`, 2);
+    const unsaved = selected.filter((row) => row.kind === 'catalog' && !row.release.saved_version);
+    if (unsaved.length) {
+        const approved = await selectOne(`Save ${unsaved.length} selected catalog tool version(s) to this workspace? This does not start tools or approve credits.`, [
+            { value: false, label: 'Cancel' }, { value: true, label: 'Save selected versions and continue to review' },
+        ], options.signal);
+        if (!approved)
+            throw new CliError('canceled', 'Nothing was saved or started.', 2);
+    }
+    process.stderr.write(`Tool start request: ${options.requestKey}\nContinue with firedrill tools start --workspace ${scope.workspace} --request-key ${options.requestKey}\n`);
+    const ids = [];
+    for (const choice of selected) {
+        if (choice.kind === 'saved') {
+            ids.push(choice.id);
+            continue;
+        }
+        if (choice.release.saved_version) {
+            ids.push(choice.release.saved_version.id);
+            continue;
+        }
+        const key = adoptionKey(options.requestKey, choice.release.id);
+        const body = { release_id: choice.release.id, duration_seconds: null,
+            install_consent: true, start_consent: false, usage_quote_id: null };
+        const read = async () => {
+            const value = await api(`${prefix}/catalog-requests/${key}`, auth);
+            return catalogRead(value, catalogSetupMatches(value, { workspace: scope.workspace, actor: scope.owner }, { key, input: body }));
+        };
+        process.stderr.write(`Saving ${terminalText(choice.release.name)}: catalog request ${key}. Recovery: firedrill tools catalog-status ${key} --workspace ${scope.workspace}\n`);
+        let receipt;
+        try {
+            const value = await api(`${prefix}/catalog-setups`, { ...auth, method: 'POST', idempotencyKey: key, body });
+            receipt = catalogRead(value, catalogSetupMatches(value, { workspace: scope.workspace, actor: scope.owner }, { key, input: body }));
+        }
+        catch {
+            try {
+                receipt = await read();
+            }
+            catch {
+                throw new CliError('catalog_acceptance_unconfirmed', `Catalog request ${key} is unconfirmed. Recover that original request; do not create another start key. No tools were started.`);
+            }
+        }
+        // Await only the original package inspection; bounded, no runtime allocation.
+        for (let attempt = 0; attempt < 20 && ['preparing', 'inspecting'].includes(receipt.state); attempt++) {
+            await sleep(1500, options.signal);
+            receipt = await read();
+        }
+        if (receipt.state !== 'saved' || !receipt.implementation_id) {
+            throw new CliError('catalog_save_pending', `Catalog request ${key} is ${receipt.state}. Inspect the original request, then continue tools start with request key ${options.requestKey}. No tools were started.`, 2);
+        }
+        ids.push(receipt.implementation_id);
+    }
+    if (new Set(ids).size !== ids.length)
+        throw new CliError('tool_selection_invalid', 'The selection resolves to duplicate saved versions. Choose each version once. No tools were started.', 2);
+    return ids;
+}