firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/workspace-registration.js

@@ -0,0 +1,383 @@
+/**
+ * Creating a workspace from the terminal (`firedrill workspace create`,
+ * `requests`, `request`, `withdraw`).
+ *
+ * Root (`accounts/native_workspace_requests.py`), all under the terminal's
+ * native session:
+ * - `GET /api/auth/native/workspace-policy` gives the terms and privacy
+ *   documents (version and URL) the human must read and accept. 503 until they
+ *   are configured.
+ * - `POST /api/auth/native/workspace-requests` with an original UUID
+ *   Idempotency-Key and exactly `{name, workspace_consent, terms_version,
+ *   terms_accepted, privacy_version, privacy_accepted}`. Replaying the same key
+ *   with the same name and the originally approved versions continues the same
+ *   request; it never creates a second organization. Every native request row
+ *   carries the versions the human approved (`terms_version`,
+ *   `privacy_version`), and a replay uses exactly those, never today's
+ *   documents.
+ * - `GET .../workspace-requests` (paged) and `.../{key}` recover the original
+ *   (`not_received` when absent). `DELETE .../{key}` with `{withdraw_consent:
+ *   true}` withdraws it only while it is provably unsent.
+ *
+ * Consent is the human's: never inferred from sign-in or a task. JSON mode needs
+ * --approve-change plus the exact document versions the human accepted.
+ *
+ * A finished request in a new organization says `reauthorization_required`:
+ * this terminal's grant is for another organization, so the human signs in to
+ * the new one with a new device authorization. Nothing here changes the
+ * current grant's organization or selected workspace on its own.
+ */
+import { randomUUID } from 'node:crypto';
+import { createInterface } from 'node:readline/promises';
+import { api, login } from './auth.js';
+import { APP_ORIGIN, CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { isTransient } from './native/control-plane.js';
+const POLICY = '/api/auth/native/workspace-policy';
+const REQUESTS = '/api/auth/native/workspace-requests';
+const PAGE_SIZE = 25;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const ORGANIZATION = /^org_[A-Za-z0-9]{1,120}$/;
+const STATES = ['not_received', 'pending', 'creating', 'uncertain', 'completed', 'withdrawn'];
+/** Sent or being sent: only replaying the same request moves it on. */
+const UNFINISHED = new Set(['pending', 'creating', 'uncertain']);
+/** Root's answers that mean "the same request is still being confirmed; send it again shortly". */
+const STILL_CREATING = new Set(['workspace_creation_pending', 'membership_pending']);
+/** A step the human must take before anything is sent: its own JSON line, or text on stderr. */
+function notice(json, value, text) {
+    if (json)
+        process.stdout.write(JSON.stringify(value) + '\n');
+    else
+        process.stderr.write(text + '\n');
+}
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const lower = (value) => value.toLowerCase();
+/** Root's version check: 1-80 characters, no spaces or controls. */
+const versionText = (value) => typeof value === 'string' && value.length >= 1 && value.length <= 80
+    && ![...value].some((c) => c.charCodeAt(0) < 33);
+function documentMatches(value) {
+    if (!object(value) || Object.keys(value).length !== 2 || !versionText(value.version) || typeof value.url !== 'string')
+        return false;
+    try {
+        const url = new URL(value.url);
+        return url.protocol === 'https:' && !!url.hostname && !url.username && !url.password && !url.hash;
+    }
+    catch {
+        return false;
+    }
+}
+export function documentsMatch(value) {
+    return object(value) && Object.keys(value).length === 2 && documentMatches(value.terms) && documentMatches(value.privacy);
+}
+/** One workspace request as root returns it, for this person and (when given) this exact key. */
+export function workspaceRequestMatches(value, owner, key) {
+    if (!object(value))
+        return false;
+    const v = value;
+    if (v.schema !== 'firedrill.workspace-request.v1' || typeof v.actor_id !== 'string' || lower(v.actor_id) !== owner
+        || typeof v.request_key !== 'string' || !UUID.test(v.request_key) || (key !== undefined && v.request_key !== key)
+        || !STATES.includes(v.state) || typeof v.workspace_available !== 'boolean'
+        || typeof v.reauthorization_required !== 'boolean')
+        return false;
+    if (v.workspace_id !== null && (typeof v.workspace_id !== 'string' || !UUID.test(lower(v.workspace_id))))
+        return false;
+    if (v.workos_organization_id !== null && (typeof v.workos_organization_id !== 'string' || !ORGANIZATION.test(v.workos_organization_id)))
+        return false;
+    // Root shows a workspace only while this person can still open it, and its organization only then.
+    if (v.workspace_available !== (v.workspace_id !== null))
+        return false;
+    if (v.workspace_available && v.state !== 'completed')
+        return false;
+    if (v.workos_organization_id !== null && !v.workspace_available)
+        return false;
+    if (v.reauthorization_required && v.workos_organization_id === null)
+        return false;
+    if (v.state === 'not_received')
+        return v.name === null && v.created_at === null && !v.workspace_available
+            && v.terms_version === null && v.privacy_version === null;
+    return typeof v.name === 'string' && v.name.length >= 1 && v.name.length <= 120 && typeof v.created_at === 'string'
+        && versionText(v.terms_version) && versionText(v.privacy_version);
+}
+function pageMatches(value, owner, page) {
+    if (!object(value) || !Array.isArray(value.results) || value.page !== page || value.page_size !== PAGE_SIZE
+        || !Number.isSafeInteger(value.count) || value.count < 0 || value.results.length > PAGE_SIZE
+        || (value.next !== null && typeof value.next !== 'string') || (value.previous !== null && typeof value.previous !== 'string'))
+        return false;
+    const keys = new Set();
+    for (const row of value.results) {
+        if (!workspaceRequestMatches(row, owner) || row.state === 'not_received' || keys.has(row.request_key))
+            return false;
+        keys.add(row.request_key);
+    }
+    return true;
+}
+const unconfirmed = () => new CliError('native_response_unconfirmed', 'The workspace request answer could not be confirmed. Nothing else was sent.', 2);
+/** The original request key: a lowercase UUID, exactly as root keys it. */
+export function workspaceRequestKey(value) {
+    if (!UUID.test(value))
+        throw new CliError('native_workspace_request_invalid', 'Use the original workspace request key (a lowercase UUID).', 2);
+    return value;
+}
+/** Root trims the name and refuses controls; the same rule here sends nothing root would refuse. */
+export function workspaceName(value) {
+    const name = value.trim();
+    if (name.length < 1 || name.length > 120 || /[\u0000-\u001f\u007f]/.test(value))
+        throw new CliError('workspace_name_invalid', 'Use a workspace name of 1 to 120 characters without control characters. Nothing was sent.', 2);
+    return name;
+}
+const quoted = (value) => /^[A-Za-z0-9_./:@-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+/** Continues the original: root's retained versions are used once it has the request; until then it is shown for approval again. */
+function recoveryCommand(name, key) {
+    return `firedrill workspace create ${quoted(name)} --request-key ${key}`;
+}
+/** The command a human approves for a new request: the name, the key and the exact document versions they accepted. */
+function approvedCommand(name, key, documents) {
+    return `${recoveryCommand(name, key)} --terms-version ${quoted(documents.terms)} --privacy-version ${quoted(documents.privacy)} --approve-change --json`;
+}
+export async function workspaceDocuments(owner, signal) {
+    let value;
+    try {
+        value = await api(POLICY, { actor: owner, signal });
+    }
+    catch (error) {
+        if (error instanceof CliError && error.code === 'native_workspace_terms_unavailable')
+            throw new CliError(error.code, `Creating a workspace from the terminal is not available yet. Open ${new URL('/onboarding', APP_ORIGIN).href} to create one in the browser. Nothing was sent.`, 2, error.httpStatus);
+        throw error;
+    }
+    if (!documentsMatch(value))
+        throw unconfirmed();
+    return value;
+}
+export async function recoverWorkspaceRequest(owner, key, signal) {
+    const value = await api(`${REQUESTS}/${key}`, { actor: owner, signal });
+    if (!workspaceRequestMatches(value, owner, key))
+        throw unconfirmed();
+    return value;
+}
+async function readLine(question, signal) {
+    const prompt = createInterface({ input: process.stdin, output: process.stderr, terminal: false });
+    try {
+        return await prompt.question(question, { signal });
+    }
+    finally {
+        prompt.close();
+    }
+}
+function requestText(row) {
+    const name = terminalText(row.name ?? '');
+    switch (row.state) {
+        case 'completed':
+            if (!row.workspace_available)
+                return `Workspace ${name} was created, but this account can no longer open it.`;
+            return row.reauthorization_required
+                ? `Workspace ${name} is ready (${row.workspace_id}) in a new organization. This terminal is signed in to a different one.`
+                : `Workspace ${name} is ready (${row.workspace_id}).`;
+        case 'withdrawn': return `The request for ${name} was withdrawn before it was sent. No workspace was created.`;
+        case 'not_received': return 'Firedrill has no workspace request with this key.';
+        default: return `Workspace ${name} is still being created.`;
+    }
+}
+/** What to run next for a request, in order: empty when nothing is left to do. */
+function nextCommands(row) {
+    if (row.state !== 'completed' || !row.workspace_available)
+        return [];
+    return [...(row.reauthorization_required ? [`firedrill login --organization ${row.workos_organization_id}`] : []),
+        `firedrill workspace use ${row.workspace_id}`];
+}
+const nextText = (row) => nextCommands(row).length ? `Next: ${nextCommands(row).join(', then ')}` : '';
+/** Select a ready workspace for this terminal, signing in to its organization first when the human chooses to. */
+async function useWorkspace(row, options) {
+    if (row.state !== 'completed' || !row.workspace_available || !row.workspace_id)
+        return null;
+    const use = await selectOne(row.reauthorization_required ? 'Sign in to its organization' : 'Use this workspace', [
+        { value: true, label: row.reauthorization_required ? 'Sign in to it now' : 'Use it now',
+            detail: row.reauthorization_required ? 'A new browser sign-in for the new organization.' : '' },
+        { value: false, label: 'Later', detail: nextCommands(row).join(', then ') },
+    ], options.signal);
+    if (!use)
+        return null;
+    if (row.reauthorization_required) {
+        const session = await login({ json: false, open: options.openBrowser, organization: row.workos_organization_id, signal: options.signal });
+        if (session.user.id.toLowerCase() !== options.owner)
+            throw new CliError('native_account_changed', 'A different account signed in. The workspace was not selected.', 2);
+    }
+    return api('/api/auth/native/workspaces', { method: 'POST', body: { workspace_id: row.workspace_id }, actor: options.owner, signal: options.signal });
+}
+/**
+ * Create a workspace, or continue the original request. Returns the request as
+ * root last answered it (never a guess).
+ */
+export async function createWorkspace(nameInput, options) {
+    const interactive = !options.json && process.stdin.isTTY === true;
+    const key = workspaceRequestKey(options.request ?? randomUUID());
+    let name = nameInput === undefined ? undefined : workspaceName(nameInput);
+    let versions = null;
+    if (options.termsVersion !== undefined || options.privacyVersion !== undefined) {
+        if (!versionText(options.termsVersion) || !versionText(options.privacyVersion))
+            throw new CliError('arguments_invalid', 'Pass both --terms-version and --privacy-version, as shown with the documents. Nothing was sent.', 2);
+        versions = { terms: options.termsVersion, privacy: options.privacyVersion };
+    }
+    // The original first: a finished, withdrawn or unfinished request is never replaced by a new one.
+    let replay = false;
+    if (options.request) {
+        const original = await recoverWorkspaceRequest(options.owner, key, options.signal);
+        if (original.state === 'completed')
+            return original;
+        if (original.state === 'withdrawn')
+            throw new CliError('workspace_request_withdrawn', 'This request was withdrawn before it was sent. Run firedrill workspace create without --request-key to start a new one.', 2);
+        if (UNFINISHED.has(original.state)) {
+            if (name !== undefined && name !== original.name)
+                throw new CliError('idempotency_conflict', `Request ${key} is for ${terminalText(original.name)}. Continue it with that name, or start a new request without --request-key.`, 2);
+            const retained = { terms: original.terms_version, privacy: original.privacy_version };
+            if (versions && (versions.terms !== retained.terms || versions.privacy !== retained.privacy))
+                throw new CliError('idempotency_conflict', `Request ${key} was approved with terms ${terminalText(retained.terms)} and privacy ${terminalText(retained.privacy)}. It continues only with those. Nothing was sent.`, 2);
+            // The original approval, exactly as root retained it: never today's documents, never a new assent.
+            name = original.name;
+            versions = retained;
+            replay = true;
+        }
+    }
+    if (name === undefined) {
+        if (!interactive)
+            throw new CliError('workspace_name_required', 'Pass the workspace name: firedrill workspace create <name>. Nothing was sent.', 2);
+        name = workspaceName(await readLine('Workspace name: ', options.signal));
+    }
+    if (!replay) {
+        // A new request: the human reads and accepts the current documents.
+        const documents = await workspaceDocuments(options.owner, options.signal);
+        const current = { terms: documents.terms.version, privacy: documents.privacy.version };
+        if (versions && (versions.terms !== current.terms || versions.privacy !== current.privacy))
+            throw new CliError('native_workspace_terms_changed', `The documents changed since they were shown (terms ${terminalText(current.terms)}, privacy ${terminalText(current.privacy)}). Show the human the current ones before asking again. Nothing was sent.`, 2);
+        const approval = { type: 'workspace_approval_required', name, request_key: key, terms: documents.terms, privacy: documents.privacy,
+            command: approvedCommand(name, key, current) };
+        if (interactive) {
+            process.stderr.write(`Workspace: ${terminalText(name)}\nCreating it makes you its owner in a new organization and accepts:\n`
+                + `  Terms of service (${terminalText(current.terms)}): ${terminalText(documents.terms.url)}\n`
+                + `  Privacy policy (${terminalText(current.privacy)}): ${terminalText(documents.privacy.url)}\n`);
+            const accepted = await selectOne('Create this workspace?', [
+                { value: true, label: 'Create it and accept both documents' }, { value: false, label: 'Cancel' }
+            ], options.signal);
+            if (!accepted)
+                throw new CliError('canceled', 'No workspace was requested.', 130);
+        }
+        else if (!options.approve || !versions) {
+            notice(options.json, approval, `Workspace: ${terminalText(name)}\n  Terms of service (${terminalText(current.terms)}): ${terminalText(documents.terms.url)}\n`
+                + `  Privacy policy (${terminalText(current.privacy)}): ${terminalText(documents.privacy.url)}\nAfter the human approves: ${approval.command}`);
+            throw new CliError('workspace_approval_required', 'Creating a workspace needs the human to approve its name and accept both documents. Show them the name and both document links, and run the printed command only after they approve. Nothing was sent.', 2);
+        }
+        versions = current;
+    }
+    if (!versions)
+        throw unconfirmed();
+    const recovery = recoveryCommand(name, key);
+    notice(options.json, { type: 'request_prepared', request_key: key, recovery }, `Recovery: ${recovery}`);
+    const body = { name, workspace_consent: true, terms_version: versions.terms, terms_accepted: true,
+        privacy_version: versions.privacy, privacy_accepted: true };
+    try {
+        const value = await api(REQUESTS, { method: 'POST', idempotencyKey: key, body, actor: options.owner, signal: options.signal });
+        if (!workspaceRequestMatches(value, options.owner, key) || value.name !== name
+            || value.terms_version !== versions.terms || value.privacy_version !== versions.privacy)
+            throw unconfirmed();
+        return value;
+    }
+    catch (error) {
+        if (!(error instanceof CliError) || options.signal.aborted)
+            throw error;
+        if (error.code === 'native_workspace_terms_changed')
+            throw new CliError(error.code, 'The documents changed while they were being reviewed. Run firedrill workspace create again to show the current ones. Nothing was created.', 2, error.httpStatus);
+        const answered = error.httpStatus !== null && !isTransient(error);
+        if (answered && !STILL_CREATING.has(error.code))
+            throw error;
+        // Still being confirmed, or no answer: read the original. Never sent again here.
+        const original = await recoverWorkspaceRequest(options.owner, key, options.signal).catch(() => null);
+        if (original && original.state !== 'not_received')
+            return original;
+        throw new CliError('workspace_request_unconfirmed', `The workspace request was not confirmed. Run the same request again: ${recovery}`, 2);
+    }
+}
+async function listRequests(options) {
+    const page = Number(options.page ?? '1');
+    const value = await api(`${REQUESTS}?page=${page}&page_size=${PAGE_SIZE}`, { actor: options.owner, signal: options.signal });
+    if (!pageMatches(value, options.owner, page))
+        throw unconfirmed();
+    return value;
+}
+async function withdraw(key, options) {
+    const original = await recoverWorkspaceRequest(options.owner, key, options.signal);
+    if (original.state === 'not_received')
+        throw new CliError('workspace_request_not_found', 'Firedrill has no workspace request with this key. Nothing was withdrawn.', 2);
+    if (original.state !== 'pending')
+        return original;
+    if (!options.json && process.stdin.isTTY) {
+        const yes = await selectOne(`Withdraw the request for ${terminalText(original.name)}?`, [
+            { value: true, label: 'Withdraw it', detail: 'Only possible while it has not been sent.' }, { value: false, label: 'Keep it' }
+        ], options.signal);
+        if (!yes)
+            throw new CliError('canceled', 'The request was kept.', 130);
+    }
+    else if (!options.approve) {
+        notice(true, { type: 'workspace_withdrawal_approval_required', request_key: key, name: original.name,
+            command: `firedrill workspace withdraw ${key} --approve-change --json` }, '');
+        throw new CliError('workspace_approval_required', 'Withdrawing needs the human\'s approval (--approve-change). Nothing was withdrawn.', 2);
+    }
+    const value = await api(`${REQUESTS}/${key}`, { method: 'DELETE', body: { withdraw_consent: true }, actor: options.owner, signal: options.signal });
+    if (!workspaceRequestMatches(value, options.owner, key))
+        throw unconfirmed();
+    return value;
+}
+/** `firedrill workspace create|requests|request|withdraw`. */
+export async function workspaceRegistrationCommand(args, options, output) {
+    const [action, target] = args;
+    if (action === 'create' && args.length <= 2) {
+        const row = await createWorkspace(target, options);
+        if (!options.json && process.stdin.isTTY && row.state === 'completed' && row.workspace_available) {
+            process.stdout.write(requestText(row) + '\n');
+            const session = await useWorkspace(row, options);
+            if (session)
+                output(session, `Workspace: ${terminalText(session.workspace?.name ?? 'Not selected')}`);
+            else
+                process.stdout.write(nextText(row) + '\n');
+            return;
+        }
+        output({ ...row, next_commands: nextCommands(row) }, [requestText(row),
+            UNFINISHED.has(row.state) ? `Check it again with: firedrill workspace request ${row.request_key}` : nextText(row)].filter(Boolean).join('\n'));
+        return;
+    }
+    if (action === 'requests' && args.length === 1) {
+        if (options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page))
+            throw new CliError('query_invalid', 'Use a valid page number.', 2);
+        const page = await listRequests(options);
+        output(page, [page.results.map((row) => `${row.request_key}  ${row.state}  ${terminalText(row.name ?? '')}${row.workspace_id ? '  ' + row.workspace_id : ''}`).join('\n')
+                || 'No workspace requests from this terminal.', page.next ? `More: firedrill workspace requests --page ${page.page + 1}` : ''].filter(Boolean).join('\n'));
+        return;
+    }
+    if (action === 'request' && args.length === 2) {
+        const row = await recoverWorkspaceRequest(options.owner, workspaceRequestKey(target), options.signal);
+        output({ ...row, next_commands: nextCommands(row) }, [requestText(row), UNFINISHED.has(row.state)
+                ? `If it stays like this, continue the same request: firedrill workspace create --request-key ${row.request_key} (it keeps the documents approved for it).`
+                : nextText(row)].filter(Boolean).join('\n'));
+        return;
+    }
+    if (action === 'withdraw' && args.length === 2) {
+        const row = await withdraw(workspaceRequestKey(target), options);
+        output(row, row.state === 'withdrawn' ? `Withdrawn. No workspace was created for ${terminalText(row.name ?? '')}.`
+            : `It was already sent, so it cannot be withdrawn. ${requestText(row)}`);
+        return;
+    }
+    throw new CliError('arguments_invalid', 'Use workspace create [name], workspace requests, workspace request <key> or workspace withdraw <key>.', 2);
+}
+/** The terminal chooser's "create a workspace here": the new workspace's ID once this grant can use it, otherwise null. */
+export async function createWorkspaceHere(owner, signal, openBrowser) {
+    const options = { json: false, owner, openBrowser, signal };
+    const row = await createWorkspace(undefined, options);
+    process.stderr.write(requestText(row) + '\n');
+    if (row.state !== 'completed' || !row.workspace_available || !row.workspace_id) {
+        if (UNFINISHED.has(row.state))
+            process.stderr.write(`Check it again with: firedrill workspace request ${row.request_key}\n`);
+        return null;
+    }
+    if (!row.reauthorization_required)
+        return row.workspace_id;
+    const session = await useWorkspace(row, options);
+    return session ? row.workspace_id : null;
+}

package/dist/cli/src/workspace-team-contracts.js

@@ -0,0 +1 @@
+export * from '../../contracts/workspace-team-contracts.js';

package/dist/cli/src/world-access.js

@@ -0,0 +1,231 @@
+import { api, login, openBrowser } from './auth.js';
+import { randomUUID } from 'node:crypto';
+import { APP_ORIGIN, CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { createInterface } from 'node:readline/promises';
+import { createWorkspaceHere } from './workspace-registration.js';
+export async function selectedWorkspace(options) {
+    let session;
+    try {
+        session = await api('/api/auth/native/session', { signal: options.signal });
+    }
+    catch (error) {
+        if (!(error instanceof CliError) || error.code !== 'authentication_required' || !options.interactive)
+            throw error;
+        const choice = await selectOne('Authorize Firedrill access', [{ label: 'Sign in using the browser', value: true },
+            { label: 'Cancel', value: false }], options.signal);
+        if (!choice)
+            throw new CliError('canceled', 'No sign-in was started.', 130);
+        session = await login({ json: false, open: options.openBrowser, signal: options.signal });
+    }
+    const owner = identifier(session.user.id);
+    if (options.expectedOwner && owner !== options.expectedOwner)
+        throw new CliError('native_account_changed', 'The terminal account changed. Reopen this project before selecting its workspace.', 2);
+    let workspace = options.workspace ? identifier(options.workspace) : session.workspace?.id;
+    if (!workspace && options.interactive) {
+        workspace = await chooseWorkspace(owner, options.signal, options.openBrowser);
+    }
+    if (!workspace && session.membership_sync.state === 'running')
+        throw new CliError('workspace_discovery_pending', 'Workspace access is still being checked. Use firedrill workspace list to see its progress, then select an available workspace.', 2);
+    if (!workspace)
+        throw new CliError('workspace_setup_required', `Create one with firedrill workspace create <name> after the human approves it and accepts the terms, or open ${new URL('/onboarding', APP_ORIGIN).href} to create or choose one in the browser. Then run firedrill workspace. No agent was started.`, 2);
+    workspace = identifier(workspace);
+    // The user's explicit choice establishes the same selected scope used by
+    // stream revocation checks. The actor pin prevents another process's login
+    // from inheriting this conversation's remembered authority.
+    if (workspace !== session.workspace?.id)
+        await api('/api/auth/native/workspaces', {
+            method: 'POST', body: { workspace_id: workspace }, actor: owner, signal: options.signal
+        });
+    return { owner, workspace };
+}
+export async function selectedWorld(options) {
+    const { owner, workspace } = await selectedWorkspace(options);
+    const prefix = `/api/workspaces/${workspace}/worlds`;
+    let world = options.world ? identifier(options.world) : undefined;
+    if (!world) {
+        const { savedProject } = await import('./source-connection.js');
+        world = (await savedProject({ owner, workspace }, process.cwd()))?.world;
+    }
+    if (!world && options.interactive) {
+        const action = await selectOne('Project', [{ value: 'connect', label: 'Connect this local project', detail: 'Review a private source capture and choose whether to upload it.' },
+            { value: 'connect-many', label: 'Connect multiple local folders', detail: 'Choose the agent components explicitly. One agent and one world are created.' },
+            { value: 'repository', label: 'Connect a GitHub repository', detail: 'Choose repository access in the browser.' },
+            { value: 'upload', label: 'Upload code', detail: 'Choose a source archive in the browser.' },
+            { value: 'new-world', label: 'Create a world for a saved agent' },
+            { value: 'saved', label: 'Open a saved world' }], options.signal);
+        if (action === 'repository' || action === 'upload') {
+            const url = new URL('/new', APP_ORIGIN);
+            url.searchParams.set('workspace', workspace);
+            url.searchParams.set('source', action);
+            const opened = options.openBrowser ? await openBrowser(url.href) : false;
+            process.stdout.write(`${opened ? 'Opened' : 'Open'} agent connection in the browser. Finish the repository connection or upload, then continue here. No source was transferred by this terminal command.\n${url.href}\n`);
+            const next = await selectOne('After source connection', [
+                { value: 'agent', label: 'Continue with the connected agent', detail: 'Choose its saved source and create a world here.' },
+                { value: 'world', label: 'Open a world already created in the browser' },
+                { value: 'cancel', label: 'Return later' },
+            ], options.signal);
+            if (next === 'cancel')
+                throw new CliError('canceled', 'Browser source setup stays saved. Return with firedrill when ready.', 130);
+            if (next === 'agent') {
+                const { createWorld } = await import('./world-creation.js');
+                const result = await createWorld({ ...options, json: false }, (_data, readable) => {
+                    process.stdout.write(readable.split('\n').map(terminalText).join('\n') + '\n');
+                }, undefined, { owner, workspace });
+                if (result.state === 'accepted' && result.resource_available && result.world_id)
+                    world = identifier(result.world_id);
+                else
+                    throw new CliError('world_creation_unavailable', 'The original request has no available world. Nothing was replaced or started.', 2);
+            }
+        }
+        if (action === 'connect') {
+            const { connectSource } = await import('./source-connection.js');
+            const result = await connectSource({ workspace, expectedOwner: owner, upload: false, json: false,
+                openBrowser: options.openBrowser, signal: options.signal }, (_type, _data, readable) => {
+                process.stdout.write(readable.split('\n').map(terminalText).join('\n') + '\n');
+            });
+            if (result?.state === 'connected' && result.world_id)
+                world = identifier(result.world_id);
+            else if (result)
+                throw new CliError('source_processing_pending', `Inspect source request ${result.request_key} or use firedrill connect resume ${result.request_key}. No build was started.`);
+            else
+                throw new CliError('source_kept_local', 'Source kept locally. No world was connected.', 2);
+        }
+        if (action === 'connect-many') {
+            const { connectSources } = await import('./source-batch.js');
+            const result = await connectSources({ workspace, expectedOwner: owner, upload: false, json: false,
+                openBrowser: options.openBrowser, signal: options.signal }, (_type, _data, readable) => {
+                process.stdout.write(readable.split('\n').map(terminalText).join('\n') + '\n');
+            });
+            if (result)
+                world = identifier(result.world_id);
+            else
+                throw new CliError('source_kept_local', 'Source captures kept locally. No world was connected.', 2);
+        }
+        if (action === 'new-world') {
+            const { createWorld } = await import('./world-creation.js');
+            const result = await createWorld({ ...options, json: false }, (_data, readable) => {
+                process.stdout.write(readable.split('\n').map(terminalText).join('\n') + '\n');
+            }, undefined, { owner, workspace });
+            if (result.state === 'accepted' && result.resource_available && result.world_id)
+                world = identifier(result.world_id);
+            else
+                throw new CliError('world_creation_unavailable', 'The original request has no available world. Nothing was replaced or started.', 2);
+        }
+    }
+    if (!world && options.interactive)
+        world = await choosePaged('Saved world', prefix, owner, item => ({ label: item.name, detail: item.status }), options.signal);
+    if (!world)
+        throw new CliError('world_required', 'Pass --world <id>, use firedrill connect, or create a world with firedrill worlds new <agent>.', 2);
+    return { owner, workspace, world, prefix: `${prefix}/${world}` };
+}
+export function chooseWorkspace(owner, signal, allowBrowser = true) {
+    return choosePaged('Workspace', '/api/auth/native/workspaces', owner, item => ({ label: item.name, detail: item.role }), signal, allowBrowser);
+}
+export async function refreshWorkspaceAccess(owner, signal, key) {
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(key))
+        throw new CliError('membership_discovery_request_invalid', 'Use the original workspace refresh request key.', 2);
+    try {
+        return await api('/api/auth/native/membership-sync', { method: 'POST', body: {},
+            idempotencyKey: key, actor: owner, signal });
+    }
+    catch (error) {
+        if (error instanceof CliError && error.code === 'membership_discovery_running')
+            return api('/api/auth/native/membership-sync', { actor: owner, signal });
+        throw error;
+    }
+}
+async function choosePaged(title, path, owner, describe, signal, allowBrowser = false) {
+    let number = 1, search = '';
+    while (true) {
+        const page = await api(`${path}?page=${number}&q=${encodeURIComponent(search)}`, { actor: owner, signal });
+        const choices = page.results.map(item => ({ value: item.id, ...describe(item) }));
+        if (path === '/api/auth/native/workspaces')
+            choices.push({ value: 'create-here', label: 'Create a workspace here',
+                detail: 'Name it and accept the terms in this terminal.' });
+        if (path === '/api/auth/native/workspaces')
+            choices.push({ value: 'create-workspace', label: 'Create a workspace in the browser',
+                detail: 'Optional profile setup, actual workspace creation and invitations.' });
+        if (path === '/api/auth/native/workspaces')
+            choices.push({ value: 'switch-organization', label: 'Switch organization',
+                detail: 'Authorize a new organization grant in the browser.' });
+        if (number > 1)
+            choices.unshift({ value: 'previous', label: 'Previous page', detail: '' });
+        if (page.next)
+            choices.push({ value: 'next', label: 'Next page', detail: '' });
+        if (page.membership_sync)
+            choices.push({ value: 'refresh-access',
+                label: page.membership_sync.state === 'running' ? 'Check workspace access again' : 'Refresh workspace access',
+                detail: page.membership_sync.state === 'running' ? 'Access discovery is still running.' :
+                    page.membership_sync.state === 'attention_required' ? 'The previous access refresh could not finish.' : '' });
+        choices.push({ value: 'search', label: search ? 'Change search' : 'Search entries', detail: search || '' }, { value: 'cancel', label: 'Cancel', detail: '' });
+        const value = await selectOne(title, choices, signal);
+        if (value === 'previous') {
+            number -= 1;
+            continue;
+        }
+        if (value === 'next') {
+            number += 1;
+            continue;
+        }
+        if (value === 'cancel')
+            throw new CliError('canceled', 'Selection canceled. No resource was changed.', 130);
+        if (value === 'switch-organization' && path === '/api/auth/native/workspaces') {
+            const session = await login({ json: false, open: allowBrowser, signal });
+            if (session.user.id !== owner)
+                throw new CliError('native_account_changed', 'A different account signed in. Reopen the original command before selecting its workspace.', 2);
+            number = 1;
+            search = '';
+            continue;
+        }
+        if (value === 'create-here' && path === '/api/auth/native/workspaces') {
+            const created = await createWorkspaceHere(owner, signal, allowBrowser);
+            if (created)
+                return identifier(created);
+            number = 1;
+            search = '';
+            continue;
+        }
+        if (value === 'create-workspace') {
+            const url = new URL('/onboarding', APP_ORIGIN).href;
+            process.stderr.write(`Open ${url} to create a workspace. This terminal does not create an organization or start an agent.\n`);
+            if (allowBrowser)
+                await openBrowser(url);
+            const check = await selectOne('After browser setup', [{ value: 'check', label: 'Check workspace access again' },
+                { value: 'cancel', label: 'Return later', detail: 'Use firedrill workspace when setup is complete.' }], signal);
+            if (check === 'cancel')
+                throw new CliError('canceled', 'Browser setup stays saved. Return with firedrill workspace when ready.', 130);
+            const key = randomUUID();
+            process.stderr.write(`Recovery: firedrill workspace refresh --request-key ${key}\n`);
+            await refreshWorkspaceAccess(owner, signal, key);
+            number = 1;
+            search = '';
+            continue;
+        }
+        if (value === 'refresh-access') {
+            if (page.membership_sync?.state !== 'running') {
+                const key = randomUUID();
+                process.stderr.write(`Recovery: firedrill workspace refresh --request-key ${key}\n`);
+                await refreshWorkspaceAccess(owner, signal, key);
+            }
+            number = 1;
+            continue;
+        }
+        if (value === 'search') {
+            const prompt = createInterface({ input: process.stdin, output: process.stderr, terminal: false });
+            try {
+                const entered = (await prompt.question('Find entries (blank for all): ', { signal })).trim();
+                if (entered.length > 200 || /[\u0000-\u001f\u007f-\u009f]/.test(entered))
+                    throw new CliError('search_invalid', 'Use search text up to 200 characters without terminal controls.', 2);
+                search = entered;
+                number = 1;
+            }
+            finally {
+                prompt.close();
+            }
+            continue;
+        }
+        return identifier(value);
+    }
+}

package/dist/cli/src/world-agent.js

@@ -0,0 +1,4 @@
+import { api } from './auth.js';
+// Saved world preparation read used by simulation and scenario commands.
+// The former interactive conversation client is not part of this release.
+export const preparation = (context, signal) => api(`${context.prefix}/preparation`, { actor: context.owner, workspace: context.workspace, signal });

package/dist/cli/src/world-checkpoint-scopes.js

@@ -0,0 +1,15 @@
+/** Supported native checkpoint formats and their declared fork-reset destination. */
+export const checkpointResetBaselines = {
+    owned_postgres_rows_sequences_and_sql_clock: 'prepared_world',
+    declared_sqlite_files: 'initial_checkpoint',
+    owned_postgres_and_declared_sqlite_files: 'initial_checkpoint',
+};
+export function checkpointContents(scope) {
+    if (scope === 'owned_postgres_rows_sequences_and_sql_clock')
+        return 'PostgreSQL records, sequence positions and world time settings';
+    if (scope === 'declared_sqlite_files')
+        return 'Declared SQLite stores';
+    if (scope === 'owned_postgres_and_declared_sqlite_files')
+        return 'PostgreSQL records and sequence positions plus declared SQLite stores';
+    return 'State details not recorded';
+}

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

@@ -0,0 +1,6 @@
+import { CliError } from './http.js';
+export function identifier(value) {
+    if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(value))
+        throw new CliError('identifier_invalid', 'Choose a saved item or request by its full ID.', 2);
+    return value.toLowerCase();
+}