firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/native/tool-setups.js

@@ -0,0 +1,336 @@
+/**
+ * Mixed tool setups (root `native_tool_setup*`): the one review, quote and
+ * admission flow the web app, the remote MCP and this CLI share for starting
+ * tools outside any drill.
+ *
+ * Each selected service runs in one of two lanes, decided by root:
+ *  - `pooled`: a reviewed catalog service on the shared tool pool (starting data
+ *    is a seed; `dataset_id` must be null);
+ *  - `isolated`: the whole package in its own isolated runtime, which is how an
+ *    uploaded custom package runs (starting data is a saved dataset; `seed_id`
+ *    must be null). One package appears at most once per setup.
+ *
+ * Flow: review (Idempotency-Key = request key; recovered at `requests/{key}`)
+ * -> quotes (Idempotency-Key = quote key; root keeps exactly one estimate per
+ * setup, `quote_request_key`, and replays it for that key only) -> admission of
+ * exactly that bundle digest with `start_consent`, which reserves credits and
+ * starts each child independently. Stop takes `stop_consent`. Older standalone
+ * batches stay readable through `standalone-tools.ts` for history.
+ */
+import { api } from '../auth.js';
+import { creditApprovalPolicy } from './credit-approval.js';
+import { CliError } from '../http.js';
+export const SETUP_MAX_SELECTIONS = 32;
+export const SETUP_MAX_OPERATIONS = 256;
+export const SETUP_MIN_SECONDS = 60;
+export const SETUP_MAX_SECONDS = 31_536_000;
+/** List categories root accepts. */
+export const SETUP_CATEGORIES = ['all', 'active', 'preparing', 'closed'];
+/** Summary states once no child is unfinished. */
+export const SETUP_ENDED = new Set(['stopped', 'closed']);
+/** A child instance that is running (pooled and isolated instances both say `active`). */
+export const SETUP_RUNNING = 'active';
+/** Child instance states after which it never runs again. */
+export const SETUP_CHILD_ENDED = new Set(['stopped', 'cancelled', 'canceled', 'rejected', 'failed', 'expired']);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SHA256 = /^[0-9a-f]{64}$/;
+const STATE = /^[a-z][a-z_]{0,23}$/;
+const RESPONSE_LIMIT = 4 * 1024 * 1024;
+const LANES = new Set(['pooled', 'isolated']);
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const uuid = (value) => typeof value === 'string' && UUID.test(value);
+const count = (value, min = 0) => typeof value === 'number' && Number.isSafeInteger(value) && value >= min;
+const time = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value));
+const nullableTime = (value) => value === null || time(value);
+const text = (value, max) => typeof value === 'string' && value.length >= 1 && value.length <= max;
+const state = (value) => typeof value === 'string' && STATE.test(value);
+const names = (value) => Array.isArray(value) && value.length >= 1 && value.length <= SETUP_MAX_OPERATIONS
+    && value.every((one) => text(one, 200)) && new Set(value).size === value.length;
+const lower = (value) => value.toLowerCase();
+const unconfirmed = (what) => new CliError('native_response_unconfirmed', `The ${what} response could not be confirmed. Nothing further was sent for it.`);
+const scoped = (scope, signal) => ({ actor: scope.owner, workspace: scope.workspace, signal, maximumResponseBytes: RESPONSE_LIMIT });
+const base = (scope) => `/api/workspaces/${scope.workspace}/tools/native`;
+const sameWorkspace = (value, scope) => lower(value) === lower(scope.workspace);
+function id(value, label) {
+    if (!uuid(value))
+        throw new CliError('arguments_invalid', `Use the ${label} id exactly as Firedrill printed it. Nothing was sent.`, 2);
+    return lower(value);
+}
+function query(values) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(values))
+        if (value !== undefined)
+            params.set(key, String(value));
+    return params.toString();
+}
+function pageNumber(value) {
+    const number = value ?? 1;
+    if (!Number.isSafeInteger(number) || number < 1)
+        throw new CliError('native_page_invalid', 'Use a page number of 1 or more.', 2);
+    return number;
+}
+function search(value) {
+    const trimmed = value?.trim();
+    if (trimmed !== undefined && (trimmed.length > 200 || /[\u0000-\u001f\u007f]/.test(trimmed))) {
+        throw new CliError('arguments_invalid', 'Use a search of up to 200 printable characters.', 2);
+    }
+    return trimmed || undefined;
+}
+function page(raw, row, what) {
+    if (!object(raw) || !count(raw.count) || !Array.isArray(raw.results))
+        throw unconfirmed(what);
+    return { count: raw.count, page: typeof raw.page === 'number' ? raw.page : null,
+        next: typeof raw.next === 'string' ? raw.next : null, previous: typeof raw.previous === 'string' ? raw.previous : null,
+        results: raw.results.map(row) };
+}
+function lane(value) {
+    // Root derives scope and starting data from the lane; anything else is not this contract.
+    return LANES.has(value.lane) && value.execution_scope === (value.lane === 'pooled' ? 'selected_service' : 'isolated_package')
+        && value.starting_data === (value.lane === 'pooled' ? 'seed' : 'dataset') && typeof value.has_preview === 'boolean';
+}
+function optionService(value) {
+    if (!object(value) || !text(value.service_key, 200) || !lane(value) || !count(value.operation_count, 1)
+        || value.operation_count > SETUP_MAX_OPERATIONS)
+        throw unconfirmed('tool setup options');
+    return { service_key: value.service_key, lane: value.lane, has_preview: value.has_preview,
+        execution_scope: value.execution_scope, starting_data: value.starting_data,
+        operation_count: value.operation_count };
+}
+function optionRow(value) {
+    if (!object(value) || !uuid(value.implementation_id) || !text(value.name, 200) || !text(value.version, 128)
+        || !text(value.contract_digest, 128) || typeof value.available !== 'boolean' || !Array.isArray(value.services)
+        || value.services.length > SETUP_MAX_SELECTIONS || value.available !== value.services.length > 0)
+        throw unconfirmed('tool setup options');
+    const services = value.services.map(optionService);
+    if (new Set(services.map((one) => one.service_key)).size !== services.length)
+        throw unconfirmed('tool setup options');
+    return { implementation_id: lower(value.implementation_id), name: value.name, version: value.version,
+        contract_digest: value.contract_digest, available: value.available, services };
+}
+function summaryRow(scope, expected = {}) {
+    return (value) => {
+        if (!object(value) || !uuid(value.id) || !uuid(value.workspace_id) || !uuid(value.actor_id) || !uuid(value.request_key)
+            || typeof value.original_digest !== 'string' || !SHA256.test(value.original_digest) || !state(value.state)
+            || !count(value.item_count, 1) || value.item_count > SETUP_MAX_SELECTIONS
+            || !count(value.duration_seconds, SETUP_MIN_SECONDS) || value.duration_seconds > SETUP_MAX_SECONDS
+            || !time(value.created_at) || !nullableTime(value.approved_at) || !nullableTime(value.stop_requested_at)
+            || !(value.bundle_digest === null || (typeof value.bundle_digest === 'string' && SHA256.test(value.bundle_digest)))
+            || !(value.quote_request_key === null || uuid(value.quote_request_key))
+            // An estimate exists exactly when a quote key was used; an approval needs one.
+            || (value.bundle_digest === null) !== (value.quote_request_key === null)
+            || (value.approved_at !== null && value.bundle_digest === null))
+            throw unconfirmed('tool session');
+        const row = {
+            id: lower(value.id), workspace_id: lower(value.workspace_id), actor_id: lower(value.actor_id), request_key: lower(value.request_key),
+            original_digest: value.original_digest, state: value.state, item_count: value.item_count, duration_seconds: value.duration_seconds,
+            created_at: value.created_at, approved_at: value.approved_at, stop_requested_at: value.stop_requested_at,
+            bundle_digest: value.bundle_digest, quote_request_key: value.quote_request_key === null ? null : lower(value.quote_request_key),
+        };
+        if (!sameWorkspace(row.workspace_id, scope) || (expected.setupId !== undefined && row.id !== expected.setupId)
+            || (expected.requestKey !== undefined && row.request_key !== expected.requestKey))
+            throw unconfirmed('tool session');
+        return row;
+    };
+}
+function itemRow(value) {
+    if (!object(value) || !count(value.position) || value.position >= SETUP_MAX_SELECTIONS || !LANES.has(value.lane)
+        || !uuid(value.implementation_id) || !text(value.name, 200) || !text(value.service_key, 200) || !names(value.operations)
+        || !state(value.admission_state) || !(value.failure_code === null || text(value.failure_code, 128))
+        || !(value.instance_id === null || uuid(value.instance_id)) || !(value.instance_state === null || state(value.instance_state))
+        || !(value.instance_path === null || text(value.instance_path, 512)) || !nullableTime(value.terminal_at)
+        || !(value.pooled_batch_id === null || uuid(value.pooled_batch_id)))
+        throw unconfirmed('tool session');
+    // A child has an instance, its state and path together; only a pooled child names its pool batch.
+    const instance = value.instance_id !== null;
+    if ((value.instance_state !== null) !== instance || (value.instance_path !== null) !== instance
+        || (value.lane === 'isolated' && value.pooled_batch_id !== null)
+        || (value.lane === 'pooled' && instance && value.pooled_batch_id === null))
+        throw unconfirmed('tool session');
+    return { position: value.position, lane: value.lane, implementation_id: lower(value.implementation_id), name: value.name,
+        service_key: value.service_key, operations: [...value.operations], admission_state: value.admission_state,
+        failure_code: value.failure_code, instance_id: instance ? lower(value.instance_id) : null,
+        instance_state: value.instance_state, instance_path: value.instance_path,
+        terminal_at: value.terminal_at, pooled_batch_id: value.pooled_batch_id === null ? null : lower(value.pooled_batch_id) };
+}
+function quoteRow(value) {
+    if (!object(value) || !LANES.has(value.lane) || !uuid(value.quote_id) || !text(value.activity, 64) || !text(value.denomination, 64)
+        || !count(value.credit_scale, 1) || !count(value.estimated_units) || !count(value.maximum_units)
+        || value.estimated_units > value.maximum_units || !time(value.expires_at))
+        throw unconfirmed('tool quote');
+    // The pool quotes preparation and running time for the whole pool lane; each isolated child has its own runtime quote.
+    if (value.lane === 'pooled' ? value.position !== null || (value.component !== 'baseline' && value.component !== 'runtime')
+        : !count(value.position) || value.position >= SETUP_MAX_SELECTIONS || value.component !== 'runtime')
+        throw unconfirmed('tool quote');
+    return { ...creditApprovalPolicy(value), position: value.position, lane: value.lane, component: value.component,
+        quote_id: lower(value.quote_id), activity: value.activity, denomination: value.denomination, credit_scale: value.credit_scale,
+        estimated_units: value.estimated_units, maximum_units: value.maximum_units, expires_at: value.expires_at };
+}
+/** Saved versions in the workspace with the lane each service would start in (newest name order, `page_size` up to 100). */
+export async function listSetupOptions(scope, input) {
+    const size = input.pageSize ?? 32;
+    if (!Number.isSafeInteger(size) || size < 1 || size > 100)
+        throw new CliError('native_page_invalid', 'Use a page size from 1 to 100.', 2);
+    return page(await api(`${base(scope)}/setup-options?${query({ page: pageNumber(input.page), page_size: size, q: search(input.search) })}`, scoped(scope, input.signal)), optionRow, 'tool setup options');
+}
+/** One service of a saved version: its exact operation names and lane. */
+export async function getSetupOption(scope, input) {
+    const implementationId = id(input.implementationId, 'tool version');
+    if (!text(input.serviceKey, 200))
+        throw new CliError('arguments_invalid', 'Use a service key from firedrill tools runnable. Nothing was sent.', 2);
+    const raw = await api(`${base(scope)}/setup-options/${implementationId}?${query({ service_key: input.serviceKey })}`, scoped(scope, input.signal));
+    if (!object(raw) || !uuid(raw.implementation_id) || lower(raw.implementation_id) !== implementationId
+        || raw.service_key !== input.serviceKey || !text(raw.contract_digest, 128) || !names(raw.operations) || !lane(raw))
+        throw unconfirmed('tool version');
+    return { implementation_id: implementationId, contract_digest: raw.contract_digest, service_key: raw.service_key, operations: [...raw.operations],
+        lane: raw.lane, has_preview: raw.has_preview, execution_scope: raw.execution_scope,
+        starting_data: raw.starting_data };
+}
+/**
+ * Review an exact selection (nothing is allocated or charged). The same request
+ * key with the same body replays the original; a lost answer is recovered with
+ * `recoverSetup`, never sent again under another key. The children are read
+ * back so the setup holds exactly what was asked, in order.
+ */
+export async function reviewSetup(scope, input) {
+    const requestKey = id(input.requestKey, 'request');
+    checkSelections(input.durationSeconds, input.selections);
+    const body = { duration_seconds: input.durationSeconds, selections: input.selections.map((one) => ({
+            implementation_id: one.implementation_id, service_key: one.service_key, operations: [...one.operations],
+            seed_id: one.seed_id, dataset_id: one.dataset_id
+        })) };
+    const raw = await api(`${base(scope)}/setups`, { ...scoped(scope, input.signal), method: 'POST', idempotencyKey: requestKey, body });
+    const setup = summaryRow(scope, { requestKey })(raw);
+    if (setup.duration_seconds !== input.durationSeconds || setup.item_count !== input.selections.length)
+        throw unconfirmed('tool session');
+    const items = await setupItems(scope, { setup, signal: input.signal });
+    const asked = input.selections.map((one) => `${lower(one.implementation_id)}\0${one.service_key}\0${[...one.operations].sort().join('\0')}`);
+    const held = items.map((one) => `${one.implementation_id}\0${one.service_key}\0${[...one.operations].sort().join('\0')}`);
+    if (asked.join('\n') !== held.join('\n'))
+        throw unconfirmed('tool session');
+    return { setup, items };
+}
+/** The original review made under a request key by this user, or null when none was made. */
+export async function recoverSetup(scope, input) {
+    const requestKey = id(input.requestKey, 'request');
+    try {
+        return summaryRow(scope, { requestKey })(await api(`${base(scope)}/setups/requests/${requestKey}`, scoped(scope, input.signal)));
+    }
+    catch (error) {
+        if (error instanceof CliError && error.httpStatus === 404)
+            return null;
+        throw error;
+    }
+}
+export async function getSetup(scope, input) {
+    const setupId = id(input.setupId, 'tool session');
+    return summaryRow(scope, { setupId })(await api(`${base(scope)}/setups/${setupId}`, scoped(scope, input.signal)));
+}
+/** Tool sessions in the workspace, newest first (25 per page). `preparing`: nothing running yet but not ended. */
+export async function listSetups(scope, input) {
+    if (input.category !== undefined && !SETUP_CATEGORIES.includes(input.category)) {
+        throw new CliError('arguments_invalid', `Use --state ${SETUP_CATEGORIES.join('|')}.`, 2);
+    }
+    return page(await api(`${base(scope)}/setups?${query({ page: pageNumber(input.page), page_size: 25, category: input.category, q: search(input.search) })}`, scoped(scope, input.signal)), summaryRow(scope), 'tool sessions');
+}
+/** Every child of a setup in position order (at most 32, one page). */
+export async function setupItems(scope, input) {
+    const raw = page(await api(`${base(scope)}/setups/${input.setup.id}/items?${query({ page: 1, page_size: SETUP_MAX_SELECTIONS })}`, scoped(scope, input.signal)), itemRow, 'tool session');
+    if (raw.count !== input.setup.item_count || raw.results.length !== input.setup.item_count
+        || !raw.results.every((one, index) => one.position === index))
+        throw unconfirmed('tool session');
+    // The shared pool runs all pooled children of one setup as one batch.
+    const batches = new Set(raw.results.flatMap((one) => one.pooled_batch_id ? [one.pooled_batch_id] : []));
+    if (batches.size > 1)
+        throw unconfirmed('tool session');
+    return raw.results;
+}
+/**
+ * The setup's one estimate. Quoting reserves nothing. Root keeps the first quote
+ * key it saw for a setup and replays that estimate for it; any other key is
+ * refused (`native_tool_setup_quote_original_required`), so a setup is never
+ * re-quoted. After approval or a stop, an unquoted setup cannot be quoted.
+ */
+export async function quoteSetup(scope, input) {
+    const requestKey = id(input.requestKey, 'quote request');
+    const raw = await api(`${base(scope)}/setups/${input.setup.id}/quotes`, { ...scoped(scope, input.signal), method: 'POST', idempotencyKey: requestKey, body: {} });
+    if (!object(raw) || raw.setup_id !== input.setup.id || raw.setup_digest !== input.setup.original_digest
+        || typeof raw.bundle_digest !== 'string' || !SHA256.test(raw.bundle_digest) || !Array.isArray(raw.quotes))
+        throw unconfirmed('tool quote');
+    const quotes = raw.quotes.map(quoteRow);
+    // Exactly two pool quotes when any child is pooled, and one runtime quote per isolated child, in position order.
+    const pooled = quotes.filter((one) => one.lane === 'pooled');
+    const isolated = quotes.filter((one) => one.lane === 'isolated');
+    const isolatedPositions = input.items.filter((one) => one.lane === 'isolated').map((one) => one.position);
+    const anyPooled = input.items.some((one) => one.lane === 'pooled');
+    if ((anyPooled ? pooled.length !== 2 || pooled[0].component !== 'baseline' || pooled[1].component !== 'runtime' : pooled.length !== 0)
+        || isolated.map((one) => one.position).join(',') !== isolatedPositions.join(',')
+        || new Set(quotes.map((one) => one.quote_id)).size !== quotes.length || !quotes.length
+        || pooled.some((one) => one.denomination !== pooled[0].denomination || one.credit_scale !== pooled[0].credit_scale))
+        throw unconfirmed('tool quote');
+    return { setup_id: input.setup.id, setup_digest: input.setup.original_digest, bundle_digest: raw.bundle_digest, quote_key: requestKey, quotes };
+}
+/**
+ * Approve exactly this estimate: root reserves its credits and starts each child.
+ * Repeating the same admission continues it; a different bundle is refused.
+ */
+export async function admitSetup(scope, input) {
+    const raw = await api(`${base(scope)}/setups/${input.quotes.setup_id}/admit`, { ...scoped(scope, input.signal), method: 'POST', body: { bundle_digest: input.quotes.bundle_digest, start_consent: true, credit_approval: input.creditApproval === true } });
+    const setup = summaryRow(scope, { setupId: input.quotes.setup_id })(raw);
+    if (setup.original_digest !== input.quotes.setup_digest || setup.bundle_digest !== input.quotes.bundle_digest || setup.approved_at === null)
+        throw unconfirmed('tool session');
+    return setup;
+}
+/** Ask root to stop every child (idempotent). Acceptance is not proof that storage or processes are gone. */
+export async function stopSetup(scope, input) {
+    const setupId = id(input.setupId, 'tool session');
+    const setup = summaryRow(scope, { setupId })(await api(`${base(scope)}/setups/${setupId}`, { ...scoped(scope, input.signal), method: 'DELETE', body: { stop_consent: true } }));
+    if (setup.stop_requested_at === null)
+        throw unconfirmed('tool session');
+    return setup;
+}
+/**
+ * A new review of a stopped, never-approved setup: root copies its exact retained selections, seeds and duration.
+ * It reserves and starts nothing. The same request key returns the same replacement, and root refuses one whose
+ * key belongs to another original, or an approved or still-open source (`native_tool_setup_replacement_requires_unused_stop`).
+ */
+export async function replaceSetup(scope, input) {
+    const setupId = id(input.setupId, 'tool session');
+    const requestKey = id(input.requestKey, 'request');
+    const raw = await api(`${base(scope)}/setups/${setupId}/replacement-review`, { ...scoped(scope, input.signal), method: 'POST', body: { request_key: requestKey, replace_consent: true } });
+    if (!object(raw) || Object.keys(raw).length !== 2 || !uuid(raw.previous_setup_id) || lower(raw.previous_setup_id) !== setupId) {
+        throw unconfirmed('replacement review');
+    }
+    const setup = summaryRow(scope, { requestKey })(raw.setup);
+    if (setup.id === setupId || setup.actor_id !== lower(scope.owner))
+        throw unconfirmed('replacement review');
+    return setup;
+}
+function checkSelections(durationSeconds, selections) {
+    if (!Number.isSafeInteger(durationSeconds) || durationSeconds < SETUP_MIN_SECONDS || durationSeconds > SETUP_MAX_SECONDS) {
+        throw new CliError('tool_duration_invalid', `Choose a duration from ${SETUP_MIN_SECONDS} seconds to one year. Nothing was sent.`, 2);
+    }
+    if (!Array.isArray(selections) || selections.length < 1 || selections.length > SETUP_MAX_SELECTIONS
+        || !selections.every((one) => object(one) && uuid(one.implementation_id) && text(one.service_key, 200) && names(one.operations)
+            && (one.seed_id === null || uuid(one.seed_id)) && (one.dataset_id === null || uuid(one.dataset_id))
+            && (one.seed_id === null || one.dataset_id === null))) {
+        throw new CliError('tool_selection_invalid', `Choose 1 to ${SETUP_MAX_SELECTIONS} tools, each with 1 to ${SETUP_MAX_OPERATIONS} distinct operations, `
+            + 'and at most one of seed_id (shared pool) or dataset_id (isolated). Nothing was sent.', 2);
+    }
+}
+/** A selection file: exactly root's review input `{duration_seconds, selections}`. */
+export function parseSetupInput(value) {
+    const keys = 'dataset_id,implementation_id,operations,seed_id,service_key';
+    if (!object(value) || Object.keys(value).some((key) => key !== 'duration_seconds' && key !== 'selections')
+        || !Array.isArray(value.selections) || !value.selections.every((one) => object(one) && Object.keys(one).sort().join(',') === keys)) {
+        throw new CliError('tool_selection_invalid', 'Use a file with exactly {"duration_seconds", "selections": [{"implementation_id", "service_key", '
+            + '"operations", "seed_id", "dataset_id"}]}. Nothing was sent.', 2);
+    }
+    const selections = value.selections.map((one) => ({
+        implementation_id: typeof one.implementation_id === 'string' ? lower(one.implementation_id) : '',
+        service_key: one.service_key, operations: one.operations,
+        seed_id: typeof one.seed_id === 'string' ? lower(one.seed_id) : one.seed_id,
+        dataset_id: typeof one.dataset_id === 'string' ? lower(one.dataset_id) : one.dataset_id
+    }));
+    checkSelections(value.duration_seconds, selections);
+    return { durationSeconds: value.duration_seconds, selections };
+}

package/dist/cli/src/native/world-reuse.js

@@ -0,0 +1,288 @@
+/**
+ * World definition reuse (Plan20 R10; root `native_world_reuse.py`, contract
+ * `accounts/native_world_reuse_catalog.py`, base `/native-world-reuse`).
+ *
+ * - Sharing is per exact immutable world revision, with workspaces of the same
+ *   organization only. An administrator of the owner workspace grants read or
+ *   read-and-use, lists grants and revokes.
+ * - A grant shares the closed declaration only: references and configuration
+ *   names, never the donor's descriptor, sources, configuration values,
+ *   credentials, spending or execution. It never grants the declaration's own
+ *   dependencies (tool versions, library versions); each needs its own access.
+ * - A fork is an explicit, approved private copy into a new world of this
+ *   workspace, bound to this workspace's agent and descriptor revision, from a
+ *   definition the caller supplies (the source as read, or remapped). It is
+ *   pinned to the source's exact digest. Archive and state forks of tools are
+ *   a different thing and are not touched here.
+ * - A lost fork answer is read back by its request key, or withdrawn while it
+ *   never landed; never sent again under a new key.
+ * Nothing here provisions, runs or spends anything.
+ */
+import { api } from '../auth.js';
+import { CliError } from '../http.js';
+import { SHA256_HEX } from './contracts.js';
+export const WORLD_DEPENDENT_KINDS = ['fork', 'campaign'];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const RESPONSE_LIMIT = 4 * 1024 * 1024;
+const PAGE = 25;
+const PAGE_KEYS = 'count,next,page,page_size,previous,results';
+const SUMMARY_KEYS = 'can_use,created_at,definition_digest,id,name,owner_workspace_id,revision';
+const DETAIL_KEYS = 'can_use,created_at,definition,definition_digest,id,name,owner_workspace_id,revision';
+const GRANT_KEYS = 'allow_use,created_at,id,recipient_workspace_id,request_key,revision_id,revoked_at';
+const FORK_KEYS = 'created_at,id,request_key,source_digest,source_revision_id,target_digest,target_revision_id,world_id';
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const uuid = (value) => typeof value === 'string' && UUID.test(value);
+const sha = (value) => typeof value === 'string' && SHA256_HEX.test(value);
+const time = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value));
+const keys = (value) => Object.keys(value).sort().join(',');
+const unconfirmed = (what) => new CliError('native_response_unconfirmed', `The ${what} response could not be confirmed. Nothing further was sent for it.`);
+const scoped = (scope, signal) => ({ actor: scope.owner, workspace: scope.workspace, signal, maximumResponseBytes: RESPONSE_LIMIT });
+const base = (scope) => `/api/workspaces/${scope.workspace}/native-world-reuse`;
+/** A UUID argument exactly as Firedrill printed it, lowercased. */
+export function worldReuseId(value, label) {
+    if (!uuid(value))
+        throw new CliError('arguments_invalid', `Use the ${label} exactly as Firedrill printed it. Nothing was sent.`, 2);
+    return value.toLowerCase();
+}
+function pageNumber(value) {
+    const page = value ?? 1;
+    if (!Number.isSafeInteger(page) || page < 1)
+        throw new CliError('arguments_invalid', 'Use --page with a positive page number.', 2);
+    return page;
+}
+/** Root's standard page envelope for the 25-row page that was asked for. */
+function pageOf(raw, page, row, what) {
+    if (!object(raw) || keys(raw) !== PAGE_KEYS || !Number.isSafeInteger(raw.count) || raw.count < 0 || raw.page !== page
+        || raw.page_size !== PAGE || (raw.next !== null && typeof raw.next !== 'string') || (raw.previous !== null && typeof raw.previous !== 'string')
+        || !Array.isArray(raw.results) || raw.results.length > PAGE || (raw.next !== null) !== (page * PAGE < raw.count))
+        throw unconfirmed(what);
+    return { count: raw.count, page, next: raw.next, previous: raw.previous, results: raw.results.map(row) };
+}
+function worldRow(withDefinition) {
+    return (value) => {
+        if (!object(value) || keys(value) !== (withDefinition ? DETAIL_KEYS : SUMMARY_KEYS) || !uuid(value.id) || !uuid(value.owner_workspace_id)
+            || typeof value.name !== 'string' || [...value.name].length > 120 || !Number.isSafeInteger(value.revision) || value.revision < 1
+            || !sha(value.definition_digest) || !time(value.created_at) || typeof value.can_use !== 'boolean'
+            || (withDefinition && !object(value.definition)))
+            throw unconfirmed('world version');
+        return { id: value.id.toLowerCase(), owner_workspace_id: value.owner_workspace_id.toLowerCase(), name: value.name, revision: value.revision,
+            definition_digest: value.definition_digest, created_at: value.created_at, can_use: value.can_use,
+            ...(withDefinition ? { definition: value.definition } : {}) };
+    };
+}
+function grantRow(revisionId) {
+    return (value) => {
+        if (!object(value) || keys(value) !== GRANT_KEYS || !uuid(value.id) || typeof value.revision_id !== 'string' || value.revision_id.toLowerCase() !== revisionId
+            || !uuid(value.recipient_workspace_id) || typeof value.allow_use !== 'boolean' || !uuid(value.request_key) || !time(value.created_at)
+            || !(value.revoked_at === null || time(value.revoked_at)))
+            throw unconfirmed('world sharing');
+        return { id: value.id.toLowerCase(), revision_id: revisionId, recipient_workspace_id: value.recipient_workspace_id.toLowerCase(),
+            allow_use: value.allow_use, request_key: value.request_key.toLowerCase(), created_at: value.created_at, revoked_at: value.revoked_at };
+    };
+}
+function forkRow(value) {
+    if (!object(value) || keys(value) !== FORK_KEYS || !uuid(value.id) || !uuid(value.source_revision_id) || !sha(value.source_digest)
+        || !uuid(value.target_revision_id) || !sha(value.target_digest) || !uuid(value.world_id) || !uuid(value.request_key)
+        || !time(value.created_at))
+        throw unconfirmed('world fork');
+    return { id: value.id.toLowerCase(), source_revision_id: value.source_revision_id.toLowerCase(), source_digest: value.source_digest,
+        target_revision_id: value.target_revision_id.toLowerCase(), target_digest: value.target_digest, world_id: value.world_id.toLowerCase(),
+        request_key: value.request_key.toLowerCase(), created_at: value.created_at };
+}
+function campaignRow(value) {
+    if (!object(value) || keys(value) !== 'created_at,id,state' || !uuid(value.id) || typeof value.state !== 'string' || !value.state
+        || !time(value.created_at))
+        throw unconfirmed('world dependents');
+    return { id: value.id.toLowerCase(), state: value.state, created_at: value.created_at };
+}
+/** World revisions this workspace can read (its own and those shared with it), newest first, by declaration name prefix. */
+export async function listReusableWorlds(scope, input) {
+    const page = pageNumber(input.page);
+    const params = new URLSearchParams({ page: String(page), page_size: String(PAGE) });
+    if (input.search !== undefined) {
+        // Root counts characters (code points), not UTF-16 units.
+        if ([...input.search].length > 120)
+            throw new CliError('arguments_invalid', 'Use a world name prefix of up to 120 characters.', 2);
+        if (input.search)
+            params.set('q', input.search);
+    }
+    return pageOf(await api(`${base(scope)}/revisions?${params}`, scoped(scope, input.signal)), page, worldRow(false), 'world versions');
+}
+/** One readable world revision with its closed declaration. */
+export async function getReusableWorld(scope, input) {
+    const revisionId = worldReuseId(input.revisionId, 'world version id');
+    const row = worldRow(true)(await api(`${base(scope)}/revisions/${revisionId}`, scoped(scope, input.signal)));
+    if (row.id !== revisionId)
+        throw unconfirmed('world version');
+    return row;
+}
+/** The sharing grants of one world revision this workspace owns, newest first, revoked ones included. Administrators only. */
+export async function listWorldGrants(scope, input) {
+    const revisionId = worldReuseId(input.revisionId, 'world version id');
+    const page = pageNumber(input.page);
+    const raw = await api(`${base(scope)}/revisions/${revisionId}/grants?page=${page}&page_size=${PAGE}`, scoped(scope, input.signal));
+    return pageOf(raw, page, grantRow(revisionId), 'world sharing');
+}
+/**
+ * Share one exact world revision with another workspace of this organization
+ * under the caller's request key. The same key returns the original grant
+ * (revoked or not); a different recipient or access under it is refused.
+ * Administrators only; the human must approve first.
+ */
+export async function shareWorldVersion(scope, input) {
+    const revisionId = worldReuseId(input.revisionId, 'world version id');
+    const recipient = worldReuseId(input.recipientWorkspaceId, 'workspace id');
+    const requestKey = worldReuseId(input.requestKey, 'request key');
+    if (recipient === scope.workspace.toLowerCase()) {
+        throw new CliError('arguments_invalid', 'Share with another workspace of this organization; this one already owns the world. Nothing was sent.', 2);
+    }
+    const row = grantRow(revisionId)(await api(`${base(scope)}/revisions/${revisionId}/grants`, {
+        ...scoped(scope, input.signal), method: 'POST', body: { request_key: requestKey, recipient_workspace_id: recipient, allow_use: input.allowUse }
+    }));
+    if (row.request_key !== requestKey || row.recipient_workspace_id !== recipient || row.allow_use !== input.allowUse)
+        throw unconfirmed('world sharing');
+    return row;
+}
+/** The caller's original grant under this key, or null when root has none (which does not prove it never arrived). Administrators only. */
+export async function recoverWorldGrant(scope, input) {
+    const revisionId = worldReuseId(input.revisionId, 'world version id');
+    const requestKey = worldReuseId(input.requestKey, 'request key');
+    try {
+        const row = grantRow(revisionId)(await api(`${base(scope)}/revisions/${revisionId}/grants/requests/${requestKey}`, scoped(scope, input.signal)));
+        if (row.request_key !== requestKey)
+            throw unconfirmed('world sharing');
+        return row;
+    }
+    catch (error) {
+        if (error instanceof CliError && error.httpStatus === 404)
+            return null;
+        throw error;
+    }
+}
+/**
+ * Withdraw a sharing request that never landed, after the human approved it,
+ * so it can never land later. A grant that already landed is returned, not
+ * undone (revoke it instead). Administrators of the owner workspace only.
+ */
+export async function withdrawWorldGrantRequest(scope, input) {
+    const revisionId = worldReuseId(input.revisionId, 'world version id');
+    const requestKey = worldReuseId(input.requestKey, 'request key');
+    const raw = await api(`${base(scope)}/revisions/${revisionId}/grants/requests/${requestKey}`, {
+        ...scoped(scope, input.signal), method: 'DELETE', body: { withdraw_consent: true }
+    });
+    if (object(raw) && keys(raw) === 'request_key,state' && raw.state === 'withdrawn' && typeof raw.request_key === 'string'
+        && raw.request_key.toLowerCase() === requestKey)
+        return { state: 'withdrawn' };
+    if (object(raw) && keys(raw) === 'receipt,state' && raw.state === 'committed') {
+        const grant = grantRow(revisionId)(raw.receipt);
+        if (grant.request_key === requestKey)
+            return { state: 'committed', grant };
+    }
+    throw unconfirmed('world sharing withdrawal');
+}
+/**
+ * True when the service answered with its own refusal code: nothing was
+ * written, so the request must not be reported as lost or retried under its
+ * key. Only answers without a service code (no response, a proxy error) are lost.
+ */
+export function answeredRefusal(error) {
+    return error instanceof CliError && error.httpStatus !== null && error.code !== 'request_failed';
+}
+/** Revoke one grant after the human's approval. Idempotent: an already revoked grant is returned as it is. */
+export async function revokeWorldGrant(scope, input) {
+    const revisionId = worldReuseId(input.revisionId, 'world version id');
+    const grantId = worldReuseId(input.grantId, 'grant id');
+    const row = grantRow(revisionId)(await api(`${base(scope)}/revisions/${revisionId}/grants/${grantId}`, {
+        ...scoped(scope, input.signal), method: 'DELETE', body: { revoke_consent: true }
+    }));
+    if (row.id !== grantId || row.revoked_at === null)
+        throw unconfirmed('world sharing');
+    return row;
+}
+/**
+ * Fork one usable world revision into a new private world of this workspace,
+ * after the human approved it. The definition is the caller's (the source as
+ * read, or remapped to resources this workspace can use); the source is pinned
+ * by its exact digest. The same key returns the original fork.
+ */
+export async function forkWorld(scope, input) {
+    const sourceId = worldReuseId(input.source.id, 'world version id');
+    if (!sha(input.source.definition_digest))
+        throw unconfirmed('world version');
+    const requestKey = worldReuseId(input.requestKey, 'request key');
+    const row = forkRow(await api(`${base(scope)}/forks`, { ...scoped(scope, input.signal), method: 'POST', body: {
+            request_key: requestKey, source_revision_id: sourceId, source_digest: input.source.definition_digest,
+            agent_id: worldReuseId(input.agentId, 'agent id'), native_descriptor_id: worldReuseId(input.descriptorRevisionId, 'descriptor revision id'),
+            definition: input.definition, fork_consent: true
+        } }));
+    return checkFork(row, { sourceId, sourceDigest: input.source.definition_digest, requestKey });
+}
+/** A fork receipt for exactly this source (and digest, when known) under exactly this key. */
+export function checkFork(row, expected) {
+    if (row.source_revision_id !== expected.sourceId.toLowerCase() || row.request_key !== expected.requestKey.toLowerCase()
+        || (expected.sourceDigest !== undefined && row.source_digest !== expected.sourceDigest))
+        throw unconfirmed('world fork');
+    return row;
+}
+/** The caller's original fork under this key, as root holds it now. Never sends it again. */
+export async function recoverWorldFork(scope, input) {
+    const requestKey = worldReuseId(input.requestKey, 'request key');
+    try {
+        const fork = forkRow(await api(`${base(scope)}/forks/requests/${requestKey}`, scoped(scope, input.signal)));
+        if (fork.request_key !== requestKey)
+            throw unconfirmed('world fork');
+        return { state: 'committed', fork };
+    }
+    catch (error) {
+        if (error instanceof CliError && error.httpStatus === 404)
+            return { state: 'not_found' };
+        if (error instanceof CliError && error.code === 'native_world_fork_withdrawn')
+            return { state: 'withdrawn' };
+        throw error;
+    }
+}
+/**
+ * Withdraw a fork request that never landed, after the human approved it, so
+ * it can never land later. A fork that already landed is returned, not undone.
+ */
+export async function withdrawWorldFork(scope, input) {
+    const requestKey = worldReuseId(input.requestKey, 'request key');
+    const raw = await api(`${base(scope)}/forks/requests/${requestKey}`, { ...scoped(scope, input.signal), method: 'DELETE', body: { withdraw_consent: true } });
+    if (object(raw) && keys(raw) === 'request_key,state' && raw.state === 'withdrawn' && typeof raw.request_key === 'string'
+        && raw.request_key.toLowerCase() === requestKey)
+        return { state: 'withdrawn' };
+    if (object(raw) && keys(raw) === 'receipt,state' && raw.state === 'committed') {
+        const fork = forkRow(raw.receipt);
+        if (fork.request_key === requestKey)
+            return { state: 'committed', fork };
+    }
+    throw unconfirmed('world fork withdrawal');
+}
+/** This workspace's forks of one world revision, or its campaigns planned from it (25 per page). Never another workspace's. */
+export async function listWorldDependents(scope, input) {
+    const revisionId = worldReuseId(input.revisionId, 'world version id');
+    if (!WORLD_DEPENDENT_KINDS.includes(input.kind))
+        throw new CliError('arguments_invalid', `Use --kind ${WORLD_DEPENDENT_KINDS.join('|')} with world dependents.`, 2);
+    const page = pageNumber(input.page);
+    const raw = await api(`${base(scope)}/revisions/${revisionId}/dependents?kind=${input.kind}&page=${page}&page_size=${PAGE}`, scoped(scope, input.signal));
+    const row = input.kind === 'fork' ? (value) => {
+        const fork = forkRow(value);
+        if (fork.source_revision_id !== revisionId)
+            throw unconfirmed('world dependents');
+        return fork;
+    } : campaignRow;
+    return pageOf(raw, page, row, 'world dependents');
+}
+/** What a closed declaration references, so a human can see what a fork needs before approving it. */
+export function declarationNeeds(definition) {
+    const list = (value) => Array.isArray(value) ? value.filter(object) : [];
+    const dependencies = list(definition.dependencies);
+    const resources = list(definition.resources);
+    return {
+        simulatedTools: dependencies.filter((row) => row.mode === 'simulated').length,
+        realTools: dependencies.filter((row) => row.mode === 'real').length,
+        libraryVersions: resources.filter((row) => row.origin === 'native_library').length,
+        worldItems: resources.filter((row) => row.origin === 'world_item').length,
+        configurationNames: list(definition.configuration_names).map((row) => row.name).filter((name) => typeof name === 'string'),
+    };
+}

package/dist/cli/src/onboarding.js

@@ -0,0 +1,23 @@
+import { api, openBrowser } from './auth.js';
+import { APP_ORIGIN, CliError } from './http.js';
+import { terminalText } from './prompts.js';
+import { onboardingRead } from '../../contracts/onboarding-contracts.js';
+/** Account-only read/handoff. No workspace or local runner is required. */
+export async function onboardingCommand(args, options, output) {
+    if (args.length > 1 || args[0] && !['show', 'open'].includes(args[0]))
+        throw new CliError('arguments_invalid', 'Use onboarding show or onboarding open. Optional account setup is edited in the browser.', 2);
+    const value = onboardingRead(await api('/api/auth/native/onboarding', { signal: options.signal }));
+    const url = new URL('/onboarding', APP_ORIGIN).href;
+    output({ ...value, browser_url: url }, [
+        `Optional setup: ${value.state} · step ${value.step} of 2`,
+        value.values.display_name ? `Name: ${terminalText(value.values.display_name)}` : '',
+        value.values.role ? `Role: ${terminalText(value.catalog.roles.find(row => row.value === value.values.role)?.label || value.values.role)}` : '',
+        value.values.industry ? `Industry: ${terminalText(value.catalog.industries.find(row => row.value === value.values.industry)?.label || value.values.industry)}` : '',
+        value.values.country_code ? `Country or territory: ${value.values.country_code}` : '',
+        value.workspace_request ? `Original workspace request: ${value.workspace_request.request_key} · ${value.workspace_request.state}` : '',
+        `Open ${url} to edit, skip or resume. No agent is run and no profile change is submitted by this command.`,
+    ].filter(Boolean).join('\n'));
+    const interactive = !options.json && process.stdin.isTTY && process.stderr.isTTY;
+    if (args[0] !== 'show' && options.openBrowser && interactive)
+        await openBrowser(url);
+}