firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/simple/authoring.js

@@ -0,0 +1,270 @@
+// `firedrill library ...` and `firedrill world ...`: cloud authoring of
+// personas, scenarios and evaluations, and native world declarations that bind
+// them to a registered descriptor revision. Every change is a new immutable
+// version guarded by an expected revision and a replayable request key.
+// Nothing here provisions, runs or spends anything.
+import { CliError } from '../http.js';
+import { terminalText } from '../prompts.js';
+import { selectedWorkspace } from '../world-access.js';
+import { changeLibrary, getLibraryRevision, getWorldRevision, libraryHistory, listLibrary, LIBRARY_KINDS, saveNativeWorld, sharedHere, worldHistory } from '../native/cloud-resources.js';
+import { listNativeDescriptors, registrationKey } from '../native/registration.js';
+import { answerLost, recoverLostWrite } from '../native/metadata-requests.js';
+import { metadataRequestCommand } from './metadata-requests.js';
+import { readJsonObject } from './plan-apply.js';
+import { LIBRARY_SHARING_VERBS, libraryAccess, librarySharingCommand, parameterLines } from './library-sharing.js';
+import { WORLD_REUSE_VERBS, worldReuseCommand } from './world-reuse.js';
+const unconfirmed = (what) => new CliError('native_response_unconfirmed', `The recovered ${what} does not match this change. Nothing else was sent.`, 2);
+/** The flags that replay this exact change: a world save also names the descriptor revision it used, never the newest resolved again. */
+const replayFlags = (requestKey, descriptorRevision) => `--request ${requestKey}${descriptorRevision ? ` --descriptor-revision ${descriptorRevision}` : ''}`;
+/** The request key is printed before anything is sent, so an interrupted change can be replayed, read back or withdrawn. */
+function announce(options, emit, requestKey, kind, descriptorRevision) {
+    if (options.json)
+        emit('request_prepared', { request_key: requestKey, ...(descriptorRevision ? { descriptor_revision_id: descriptorRevision } : {}) }, '');
+    else
+        process.stderr.write(`Request key: ${requestKey} (rerun with ${replayFlags(requestKey, descriptorRevision)} to replay this exact change; `
+            + `firedrill ${kind} request ${requestKey} reads it back)\n`);
+}
+const DEFINITION_BYTES = 2 * 1024 * 1024;
+const scopeOf = (options) => selectedWorkspace({ workspace: options.workspace, signal: options.signal,
+    interactive: !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY, openBrowser: options.openBrowser && !options.json });
+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);
+}
+/** Root answers 404 for a page past the last one; say so instead of "not found". */
+const pastEnd = (page) => (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);
+    }
+    throw error;
+};
+function expectedRevision(value, fallback) {
+    if (value === undefined) {
+        if (fallback === null)
+            throw new CliError('arguments_invalid', 'Provide --expected-revision with the current revision number. Nothing was submitted.', 2);
+        return fallback;
+    }
+    if (!/^(0|[1-9][0-9]{0,9})$/.test(value))
+        throw new CliError('arguments_invalid', 'Use --expected-revision with a whole number. Nothing was submitted.', 2);
+    return Number(value);
+}
+function libraryLine(row) {
+    return `${row.kind} ${terminalText(row.name)}  v${row.revision}${row.state === 'archived' ? ' (archived)' : ''}  resource ${row.resource_id}  version ${row.id}`;
+}
+function libraryDetail(row, requestKey) {
+    return [libraryLine(row), `Digest: ${row.digest}`, `Recorded: ${terminalText(row.created_at)}`,
+        ...(row.forked_from ? [`Forked from version: ${row.forked_from}`] : []),
+        ...(requestKey ? [`Request key (rerun with --request to replay): ${requestKey}`] : [])].join('\n');
+}
+function pageText(page, line, empty) {
+    if (!page.results.length)
+        return empty;
+    return [...page.results.map(line), ...(page.next ? [`More results: rerun with --page ${(page.page ?? 1) + 1}.`] : [])].join('\n');
+}
+/**
+ * library [--kind k] [--search prefix] [--archived] [--page n]
+ * library show <version-id> | library history <resource-id>
+ * library save [<resource-id>] --kind k --file <path|-> [--expected-revision n]
+ * library archive|restore <resource-id> --kind k --expected-revision n
+ * library fork <version-id> --kind k --file <path|->
+ * save and fork also take --parameters <path|-> or --remove-parameters.
+ * Sharing, dependents and binding: see library-sharing.ts.
+ */
+export async function libraryCommand(args, options, emit) {
+    const [action, target, ...rest] = args;
+    if (action !== undefined && LIBRARY_SHARING_VERBS.has(action))
+        return librarySharingCommand(args, options, emit);
+    const usage = () => new CliError('arguments_invalid', `Use firedrill library [--kind ${LIBRARY_KINDS.join('|')}] [--search <prefix>] [--archived], library show <version-id>, library history <resource-id>, `
+        + 'library save [<resource-id>] --kind <kind> --file <path|-> [--expected-revision <n>], library archive|restore <resource-id> --kind <kind> --expected-revision <n>, '
+        + 'library fork <version-id> --kind <kind> --file <path|-> (save and fork take --parameters <path|-> or --remove-parameters), '
+        + 'library request|withdraw-request <request-key>, library bind <version-id> [--file <values.json|->], library dependents <version-id>, '
+        + 'or sharing: library recipients, grants <version-id>, share <version-id> <workspace-id> read|use, share-request <version-id> <key>, '
+        + 'revoke <version-id> <grant-id>.', 2);
+    if (rest.length)
+        throw usage();
+    if ((options.parameters !== undefined || options.removeParameters) && action !== 'save' && action !== 'fork')
+        throw usage();
+    if (options.approve !== undefined && action !== 'withdraw-request')
+        throw usage();
+    if (action === undefined || action === 'list') {
+        if (target !== undefined || options.file !== undefined || options.expectedRevision !== undefined || options.request !== undefined)
+            throw usage();
+        const scope = await scopeOf(options);
+        const number = pageNumber(options.page);
+        const page = await listLibrary(scope, { kind: options.kind, archived: options.archived === true, search: options.search,
+            page: number, signal: options.signal }).catch(pastEnd(number));
+        // A version shared from another workspace says so, and whether it can be used here; it is never editable here.
+        emit('library', page, pageText(page, (row) => libraryLine(row) + (sharedHere(scope, row) ? `  (${libraryAccess(scope, row)})` : ''), 'No library resources match. Save one with firedrill library save --kind <kind> --file <path>.'));
+        return;
+    }
+    if (options.search !== undefined || options.archived !== undefined)
+        throw usage();
+    if (action === 'request' || action === 'withdraw-request') {
+        if (!target || options.kind !== undefined || options.file !== undefined || options.expectedRevision !== undefined
+            || options.request !== undefined || options.page !== undefined)
+            throw usage();
+        const scope = await scopeOf(options);
+        await metadataRequestCommand(action, { kind: 'library', requestKey: target }, scope, options, emit, (row) => libraryDetail(row), `firedrill library withdraw-request ${target.toLowerCase()}`);
+        return;
+    }
+    if (action === 'show' || action === 'history') {
+        if (!target || options.kind !== undefined || options.file !== undefined || options.expectedRevision !== undefined || options.request !== undefined
+            || (action === 'show' && options.page !== undefined))
+            throw usage();
+        const scope = await scopeOf(options);
+        if (action === 'show') {
+            const row = await getLibraryRevision(scope, { revisionId: target, signal: options.signal });
+            emit('library_version', row, [libraryDetail(row), `Access: ${libraryAccess(scope, row)}`, ...parameterLines(row),
+                terminalText(JSON.stringify(row.definition, null, 2))].join('\n'));
+        }
+        else {
+            const number = pageNumber(options.page);
+            const page = await libraryHistory(scope, { resourceId: target, page: number, signal: options.signal }).catch(pastEnd(number));
+            // History lists only this workspace's own versions. A resource shared from
+            // another workspace has none here; only its shared versions are readable.
+            emit('library_history', page, pageText(page, libraryLine, 'This workspace owns no versions of that resource. A version shared from another '
+                + 'workspace is read by its version id: firedrill library show <version-id>.'));
+        }
+        return;
+    }
+    if (!['save', 'archive', 'restore', 'fork'].includes(action) || options.page !== undefined || !options.kind)
+        throw usage();
+    const change = action;
+    const replacing = change === 'save' || change === 'fork';
+    if (replacing !== (options.file !== undefined) || (change !== 'save' && !target))
+        throw usage();
+    // Conflicting flags are refused before anything is read from standard input.
+    if (options.parameters !== undefined && options.removeParameters)
+        throw usage();
+    if (options.parameters === '-' && options.file === '-') {
+        throw new CliError('arguments_invalid', 'Read at most one of --file and --parameters from standard input; give the other as a file path. Nothing was submitted.', 2);
+    }
+    const definition = replacing ? await readJsonObject(options.file, `the ${options.kind} definition`, options.signal, DEFINITION_BYTES) : undefined;
+    // Omitted: the existing (or forked) declaration is kept. Removed: null. Otherwise the declaration file, validated by the service.
+    const parameterSchema = options.removeParameters ? null : options.parameters === undefined ? undefined
+        : await readJsonObject(options.parameters, 'the parameter declaration', options.signal);
+    const scope = await scopeOf(options);
+    const creating = change === 'fork' || (change === 'save' && target === undefined);
+    if (creating && options.expectedRevision !== undefined && options.expectedRevision !== '0')
+        throw usage();
+    const expected = expectedRevision(options.expectedRevision, creating ? 0 : null);
+    const requestKey = registrationKey(options.request);
+    announce(options, emit, requestKey, 'library');
+    let row;
+    try {
+        row = await changeLibrary(scope, {
+            action: change, kind: options.kind, definition, parameterSchema, requestKey, signal: options.signal,
+            resourceId: change === 'fork' ? undefined : target, forkFrom: change === 'fork' ? target : undefined, expectedRevision: expected,
+        });
+    }
+    catch (error) {
+        // No answer: read the original back by its key. Never sent again here, never under a new key.
+        if (!answerLost(error) || options.signal.aborted)
+            throw error;
+        const recovered = await recoverLostWrite(scope, { kind: 'library', requestKey }, { replay: `the same command with --request ${requestKey}`, withdraw: `firedrill library withdraw-request ${requestKey}` });
+        if (recovered.kind !== options.kind || (!creating && recovered.resource_id !== target.toLowerCase())
+            || recovered.revision !== expected + 1
+            || (change === 'fork' && recovered.forked_from !== target.toLowerCase())
+            || recovered.state !== (change === 'archive' ? 'archived' : 'draft'))
+            throw unconfirmed('library change');
+        // The recovery API identifies the original key, not the attempted body.
+        // A lost conflict response can return an older definition under that key.
+        // Do not describe this receipt as confirmation that the supplied edit landed.
+        emit('native_request', { kind: 'library', request_key: requestKey, state: 'committed', receipt: recovered,
+            submitted_change_confirmed: false }, `Recovered the original library change.\n${libraryDetail(recovered, requestKey)}\nThe submitted edit is not confirmed. Inspect the original definition before continuing.`);
+        return;
+    }
+    const verb = { save: 'Saved', archive: 'Archived', restore: 'Restored', fork: 'Forked' }[change];
+    emit('library_version', row, `${verb} ${libraryDetail(row, row.request_key)}`);
+}
+function worldLine(row) {
+    return `World ${row.world_id} revision ${row.revision}: ${row.id}  descriptor ${row.native_descriptor_id}  digest ${row.definition_digest}`;
+}
+/**
+ * world save --agent <id> --file <path|-> [--descriptor-revision <id>] [--world <id> --expected-revision n]
+ * world history <world-id> [--page n] | world show <world-id> <revision-id>
+ */
+export async function worldCommand(args, options, emit) {
+    const usage = () => new CliError('arguments_invalid', 'Use firedrill world save --agent <id> --file <path|-> [--descriptor-revision <id>] [--world <id> --expected-revision <n>], '
+        + 'world history <world-id>, world show <world-id> <revision-id>, world request|withdraw-request <request-key>, '
+        + 'or reuse: world versions, version <version-id>, recipients, grants <version-id>, share <version-id> <workspace-id> read|use, '
+        + 'share-request|withdraw-share-request <version-id> <key>, revoke <version-id> <grant-id>, fork <version-id> --agent <id>, fork-request <key>, '
+        + 'withdraw-fork <key>, dependents <version-id>.', 2);
+    const [action, ...rest] = args;
+    if (action !== undefined && WORLD_REUSE_VERBS.has(action))
+        return worldReuseCommand(args, options, emit);
+    if (options.approve !== undefined && action !== 'withdraw-request')
+        throw usage();
+    if (action === 'request' || action === 'withdraw-request') {
+        if (rest.length !== 1 || options.agent !== undefined || options.file !== undefined || options.world !== undefined || options.page !== undefined
+            || options.descriptorRevision !== undefined || options.expectedRevision !== undefined || options.request !== undefined)
+            throw usage();
+        const scope = await scopeOf(options);
+        await metadataRequestCommand(action, { kind: 'world', requestKey: rest[0] }, scope, options, emit, worldLine, `firedrill world withdraw-request ${rest[0].toLowerCase()}`);
+        return;
+    }
+    if (action === 'history' || action === 'show') {
+        if (rest.length !== (action === 'show' ? 2 : 1) || options.agent !== undefined || options.file !== undefined || options.world !== undefined
+            || options.descriptorRevision !== undefined || options.expectedRevision !== undefined || options.request !== undefined
+            || (action === 'show' && options.page !== undefined))
+            throw usage();
+        const scope = await scopeOf(options);
+        if (action === 'show') {
+            const row = await getWorldRevision(scope, { worldId: rest[0], revisionId: rest[1], signal: options.signal });
+            emit('world_revision', row, worldLine(row) + '\n' + terminalText(JSON.stringify(row.definition, null, 2)));
+        }
+        else {
+            const number = pageNumber(options.page);
+            const page = await worldHistory(scope, { worldId: rest[0], page: number, signal: options.signal }).catch(pastEnd(number));
+            emit('world_history', page, pageText(page, worldLine, 'This world has no saved declaration yet.'));
+        }
+        return;
+    }
+    if (action !== 'save' || rest.length || !options.agent || !options.file || options.page !== undefined
+        || (options.world === undefined) !== (options.expectedRevision === undefined))
+        throw usage();
+    // A replay uses the descriptor revision the original did; the newest one resolved again could be a different change.
+    if (options.request !== undefined && options.descriptorRevision === undefined) {
+        const key = registrationKey(options.request);
+        throw new CliError('arguments_invalid', `A world save replay needs the descriptor revision the original used. Rerun with --request ${key} `
+            + `--descriptor-revision <id> as printed with the request key; if the original landed, firedrill world request ${key} shows it. Nothing was submitted.`, 2);
+    }
+    const definition = await readJsonObject(options.file, 'the world declaration', options.signal, DEFINITION_BYTES);
+    const scope = await scopeOf(options);
+    let descriptorRevision = options.descriptorRevision;
+    if (descriptorRevision === undefined) {
+        // Default to the agent's newest registered descriptor revision, and say so.
+        const newest = (await listNativeDescriptors(scope, { agentId: options.agent, page: 1, signal: options.signal })).results[0];
+        if (!newest)
+            throw new CliError('native_descriptor_required', 'Register a descriptor for this agent first with firedrill register. Nothing was submitted.', 2);
+        descriptorRevision = newest.id;
+    }
+    const expected = expectedRevision(options.expectedRevision, 0);
+    const requestKey = registrationKey(options.request);
+    announce(options, emit, requestKey, 'world', descriptorRevision.toLowerCase());
+    let row;
+    try {
+        row = await saveNativeWorld(scope, {
+            worldId: options.world, agentId: options.agent, descriptorRevisionId: descriptorRevision,
+            expectedRevision: expected, definition, requestKey, signal: options.signal,
+        });
+    }
+    catch (error) {
+        // No answer: read the original back by its key. Never sent again here, never under a new key.
+        if (!answerLost(error) || options.signal.aborted)
+            throw error;
+        const recovered = await recoverLostWrite(scope, { kind: 'world', requestKey }, { replay: `the same command with ${replayFlags(requestKey, descriptorRevision.toLowerCase())}`, withdraw: `firedrill world withdraw-request ${requestKey}` });
+        if ((options.world !== undefined && recovered.world_id !== options.world.toLowerCase()) || recovered.revision !== expected + 1
+            || recovered.native_descriptor_id !== descriptorRevision.toLowerCase())
+            throw unconfirmed('world change');
+        emit('native_request', { kind: 'world', request_key: requestKey, state: 'committed', receipt: recovered,
+            submitted_change_confirmed: false }, `Recovered the original world change.\n${worldLine(recovered)}\nRequest key: ${requestKey}\nThe submitted definition is not confirmed. Inspect the original before continuing.`);
+        return;
+    }
+    emit('world_revision', row, [`Saved ${worldLine(row)}`, 'Nothing was provisioned or started.',
+        `Review it with: firedrill plan --world ${row.world_id}`,
+        `Request key: ${row.request_key} (replay with ${replayFlags(row.request_key, row.native_descriptor_id)})`].join('\n'));
+}

package/dist/cli/src/simple/credit-approval.js

@@ -0,0 +1,16 @@
+import { CliError } from '../http.js';
+import { selectOne } from '../prompts.js';
+/** Separate credit consent is never inferred from execution or destructive-operation consent. */
+export async function approveCredits(quotes, options, interactive, recoveryCommand) {
+    if (!quotes.some(quote => quote.credit_approval_required))
+        return false;
+    let approved = options.approveCredits === true;
+    if (!approved && interactive)
+        approved = await selectOne('Approve the credit budget shown above?', [
+            { value: false, label: 'Not now', detail: 'Nothing is admitted.' },
+            { value: true, label: 'Approve credits', detail: 'Separately approves these exact quoted cloud-work limits.' },
+        ], options.signal);
+    if (!approved)
+        throw new CliError('credit_approval_required', `This quote requires separate credit approval. Review the displayed budget, then recover this same original request with: ${recoveryCommand} --approve-credits. Nothing was admitted.`, 2);
+    return true;
+}

package/dist/cli/src/simple/help.js

@@ -0,0 +1,98 @@
+/** Common-path commands shown first. Everything else is under `firedrill help advanced`. */
+export const COMMON_COMMANDS = ['init', 'status', 'register', 'descriptors', 'library', 'world', 'plan', 'apply', 'runner', 'run', 'watch', 'report', 'tools', 'mcp', 'help'];
+export const COMMON_HELP = `Firedrill
+
+Your coding agent (or you) drives Firedrill from this terminal or over MCP.
+Local targets run as native processes on this machine. They are not sandboxed.
+
+  firedrill init                        Sign in, choose a workspace and check this machine
+        --session-only                  Keep credentials in memory in this process (the companion);
+                                        keep it running while other commands use it
+        --persistent                    Use the OS credential store (the default when available)
+        --workspace <id>  --no-browser  --open (allow a browser in JSON mode)  --json
+  firedrill status [--plan <path|->]    Account, workspace, credential mode, companion and drivers
+  firedrill register --descriptor <path|-> --name <name>  Register a local agent (metadata only)
+  firedrill register --descriptor <path|-> --agent <id> --expected-revision <n>
+                                        Record a new descriptor revision; --request <key> replays
+        --declared-agent-name <name>    Optional: the calling coding agent's own name (recorded as self-reported)
+  firedrill descriptors --agent <id> [--page <n>] [--descriptor <id>]  Read descriptor history
+  firedrill library [--kind persona|scenario|evaluation] [--search <prefix>] [--archived]
+                                        List cloud personas, scenarios and evaluations
+  firedrill library save [<resource-id>] --kind <kind> --file <path|-> [--expected-revision <n>]
+  firedrill library show <version-id> | history <resource-id> | fork <version-id> --kind <kind> --file <path|->
+  firedrill library archive|restore <resource-id> --kind <kind> --expected-revision <n>
+                                        save and fork also take --parameters <path|-> (typed parameters) or --remove-parameters
+  firedrill library bind <version-id> [--file <values.json|->]
+                                        Fix a parameterized version's values into a new private version a world can use
+  firedrill library dependents <version-id> [--kind world|scenario]  This workspace's versions that reference it
+  firedrill library share <version-id> <workspace-id> read|use [--approve-change]
+                                        Share one exact version with another workspace of your organization (administrators)
+  firedrill library recipients | grants <version-id> | share-request <version-id> <key> | revoke <version-id> <grant-id>
+  firedrill world save --agent <id> --file <path|-> [--descriptor-revision <id>] [--world <id> --expected-revision <n>]
+                                        Declare a world for a registered agent (nothing starts); a --request replay
+                                        also passes the --descriptor-revision printed with its key
+  firedrill world history <world-id> | show <world-id> <revision-id>
+  firedrill world versions [--search <prefix>] | version <version-id>
+                                        World versions this workspace can read, its own and shared ones
+  firedrill world fork <version-id> --agent <id> [--descriptor-revision <id>] [--file <declaration.json|->] [--approve-change]
+                                        Copy a usable world version into a new private world (grants nothing it references)
+  firedrill world share <version-id> <workspace-id> read|use [--approve-change]
+                                        Share one exact world version with another workspace of your organization (administrators)
+  firedrill world recipients | grants <version-id> | share-request|withdraw-share-request <version-id> <key> | revoke <version-id> <grant-id>
+  firedrill world fork-request <key> | withdraw-fork <key> [--approve-change] | dependents <version-id> [--kind fork|campaign]
+  firedrill register|library|world request <request-key>  Read an interrupted change back by its key
+  firedrill register|library|world withdraw-request <request-key> [--approve-change]
+                                        Withdraw a change that was never saved, so it can never land
+  firedrill descriptors request|withdraw-request <request-key> --agent <id>  The same for a descriptor revision
+  firedrill plan --world <world-id> [--world-revision <id>]  Review a world's effects (no effects); a --request replay
+                                        also passes the plan's --world-revision
+  firedrill plan show <plan-id>         Read a saved review
+  firedrill apply <plan-id> --approve [--follow]  Prepare a reviewed plan (preparation reserved first, drill work in bounded
+                                        waves as drills are admitted, within the approved maximum); when ready, create its campaign
+  firedrill apply <plan-id> --request <key> [--follow]  Check an earlier apply (never applied or charged twice; asks for
+                                        approval again only if nothing is recorded under the key yet)
+  firedrill apply <plan-id> --request <key> --cancel  Cancel an eligible unstarted queue entry or unused ready preparation
+  firedrill runner enroll               Enroll this machine as a runner device for this terminal sign-in (a device identity,
+                                        not permission to run); enroll again after a new sign-in or once it expires
+  firedrill run --plan <path|-> --descriptor <path|-> --campaign <id> [--approve] [--runner <device-key>]
+                                        Approve the local plan and run that campaign's drills on this machine
+                                        Session-only: enrolls a runner for this session (key in memory; --enroll-device)
+  firedrill watch <campaign> [--follow] Show drill slots and execution states (--follow until the campaign settles,
+                                        up to 15 minutes per run)
+  firedrill report [campaign]           Read the cloud report for a simulation, with each finished drill's results
+  firedrill report <campaign> quality [--page <n>]
+                                        Per-criterion quality across drills, one compatible cohort at a time
+  firedrill report <campaign> drill <drill> [results [criterion] | effects | conversation [turn] | events [event] | actions [action] | evidence [record]]
+                                        Read a drill's per-criterion results, observations, conversation, tool calls, scenario events, target tasks and evidence
+  firedrill report <campaign> drill <drill> reassess [--request-key <key>] [--usage-quote <id> --approve-assessment]
+                                        Approve a new, separately priced evaluation of a finished drill's retained evidence (the agent is not run again)
+  firedrill report <campaign> drill <drill> reassessments | reassessment <id> [results] | reassessment-request <key> | cancel-reassessment <id>
+                                        Read reassessments and their own results (kept apart from the original), recover one by key, or cancel an unapproved one
+  firedrill simulation cancel <campaign> [--approve-change]  Cancel a simulation (running drills are revoked)
+  firedrill runner run-cleanup <device-key> <campaign-id> [--approve-change]  Recover saved shared-service closing evidence after sign-in; never start or stop processes
+  firedrill tools init [directory]      Start a custom tool package (tool.json)
+  firedrill tools validate [directory]  Check tool.json and bundle/manifest.json locally
+  firedrill tools push <package.zip>    Upload a tool package (--approve-tool-upload for automation)
+  firedrill tools definitions [--search <prefix>] | show <version-id>
+                                        Tool versions this workspace can read, its own and shared ones
+  firedrill tools definitions copy <version-id> [--approve-tool-change] | copy-status <copy-id>
+                                        Copy a shared version into a private one, inspected here before use (starts nothing)
+  firedrill tools definitions share <version-id> <workspace-id> read|use [--approve-tool-change]
+                                        Share one exact tool version with another workspace of your organization (administrators)
+  firedrill tools definitions recipients | grants <version-id> | share-request|withdraw-share-request <version-id> <key> | revoke <version-id> <grant-id>
+  firedrill tools definitions copy-request|withdraw-copy-request <key> | withdraw-copy <copy-id> | dependents <version-id> [--kind world|copy]
+  firedrill tools start                 Choose saved tools with Space, then Enter; runs in the cloud for a set time
+  firedrill tools access <session>      Connect an agent on this machine to a running tool session
+  firedrill tools state <instance> [checkpoint | edit <operation> --file <args.json> | snapshots]
+                                        Save or change a shared-pool tool's data under a replayable request key
+  firedrill tools state <instance> reset --seconds <n> | fork <snapshot> --seconds <n>
+                                        Start a new tool session from its baseline or a snapshot, after approving the estimate
+                                        Recover with --request-key <key>; approve the same --usage-quote <id> --approve-tool-change
+  firedrill tools session <session> renew --seconds <n> [--request-key <key>] [--usage-quote <id> --approve-tool-change]
+                                        Extend a running session's shared-pool tools (same tools and data), after approving the estimate
+  firedrill mcp [--agent codex|claude|other]  Show remote MCP connection guidance
+  firedrill help advanced               List every other command
+
+JSON mode (--json): no prompts, no browser opening unless --open, one JSON object per line.
+Commands from a local plan run only after you approve that exact plan.
+`;

package/dist/cli/src/simple/init.js

@@ -0,0 +1,61 @@
+import { api, login } from '../auth.js';
+import { CliError } from '../http.js';
+import { terminalText } from '../prompts.js';
+import { selectedWorkspace } from '../world-access.js';
+import { machineReport, machineText } from './status.js';
+/** The canonical path after sign-in: everything is cloud-owned except the run on this machine. */
+const NEXT = [
+    { command: 'firedrill register --descriptor <path|-> --name <name>', note: 'Register the target: metadata only, nothing uploaded' },
+    { command: 'firedrill library --kind persona|scenario|evaluation [--search <prefix>]', note: 'Reuse saved resources (and firedrill tools runnable for hosted tools); author only the gaps' },
+    { command: 'firedrill world save --agent <agent-id> --file <path|->', note: 'Declare its world; nothing starts' },
+    { command: 'firedrill plan --world <world-id>', note: 'Effect-free review with gaps and the cloud-work estimate' },
+    { command: 'firedrill apply <plan-id> --approve --follow', note: 'Only after the person approves that review and estimate; prints campaign_created' },
+    { command: 'firedrill runner enroll', note: 'Done by the person, once per terminal sign-in on this machine; again after a new sign-in or once it expires' },
+    { command: 'firedrill run --plan <path|-> --descriptor <path|-> --campaign <campaign-id>', note: 'Runs the drills here; add --approve only after the person approves the exact local plan' },
+    { command: 'firedrill watch <campaign-id> --follow', note: 'Until watch_done shows settled: true; otherwise run its next_command' },
+    { command: 'firedrill report <campaign-id>', note: 'Per-drill, per-criterion results with evidence' },
+];
+/**
+ * Sign-in, workspace selection and local capability discovery. Uploads nothing
+ * and makes no model call. The terminal always signs in with device
+ * authorization that a person approves in the browser. Where the platform enables
+ * agent registration, its auth.md describes it (firedrill signup guide reads it),
+ * and it still ends in that person's own claim and consent; init never claims
+ * registration support the platform has not published.
+ */
+export async function initCommand(args, options, emit) {
+    if (args.length)
+        throw new CliError('arguments_invalid', 'Use firedrill init with optional --session-only or --persistent, --workspace <id>, --no-browser, --open and --json.', 2);
+    const interactive = !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+    const openBrowser = options.openBrowser && (!options.json || options.explicitOpen);
+    const mode = options.mode;
+    let session;
+    try {
+        session = await api('/api/auth/native/session', { signal: options.signal });
+    }
+    catch (error) {
+        // An unavailable OS store goes through login(), which reports the platform
+        // remediation (including --session-only) instead of a bare unlock message.
+        if (!(error instanceof CliError) || !['authentication_required', 'credential_store_unavailable'].includes(error.code))
+            throw error;
+        session = await login({ json: options.json, open: options.openBrowser, explicitOpen: options.explicitOpen, signal: options.signal });
+    }
+    const scope = await selectedWorkspace({ workspace: options.workspace, interactive, signal: options.signal, openBrowser });
+    const machine = await machineReport(options.signal);
+    emit('init', {
+        account: { id: session.user.id, email: session.user.email }, workspace_id: scope.workspace, credential_mode: mode, machine,
+        coding_agent_sign_in: { terminal: 'device_authorization', approved_by: 'person_in_browser',
+            registration_guide_command: 'firedrill signup guide' },
+        next: NEXT, uploaded: false, model_called: false,
+    }, [
+        `Signed in as ${terminalText(session.user.email)}.`,
+        `Workspace: ${scope.workspace}`,
+        `Credentials: ${mode === 'session' ? 'memory only, for the companion session' : 'OS credential store'}`,
+        ...machineText(machine),
+        'A coding agent signs in the same way: it relays the link and code, and a person approves in the browser.',
+        'firedrill signup guide reads the platform\'s agent registration instructions, if it publishes them.',
+        'Next (cloud-owned, except the run on this machine):',
+        ...NEXT.map((step, index) => `  ${index + 1}. ${step.command}\n     ${step.note}`),
+        'Nothing was uploaded and no model was called.',
+    ].join('\n'));
+}