@onesi/genesis-cli 0.0.1-stage → 0.2.0

package/dist/flocks.js

@@ -0,0 +1,326 @@
+import { Option } from 'commander';
+import { readFunctionJson } from './function-input.js';
+import { safe, table } from './output.js';
+/** Keys that must never reach a terminal or log, even if a server one day returned them. */
+const SECRET_KEY = /^(?:credential_ref|sealed|envelope|ciphertext|enc|ct|token|access_token|refresh_token|secret|password|api_key|api_key_secret_ref|key_material)$/i;
+export function scrub(value) {
+    if (Array.isArray(value))
+        return value.map(scrub);
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, SECRET_KEY.test(k) ? '[redacted]' : scrub(v)]));
+    return value;
+}
+/** A reference to a key the org already holds in Blinds or Secret Manager (never the key itself). */
+export function checkSecretRef(ref) {
+    // A Blinds variable name in your org, written NAME or blinds:NAME. Secret Manager names are not supported (Blinds answers 422).
+    if (!/^(?:blinds:)?[A-Za-z][A-Za-z0-9_]{0,127}$/.test(ref) || /^(?:sk_|AIza|ghp_|xox[a-z]_)/i.test(ref) || ref.length >= 40)
+        throw new Error('--api-key-secret-ref takes the name of a Blinds variable your org already holds (NAME or blinds:NAME), never the key itself.');
+    return ref;
+}
+/** One line from stdin. On a terminal the keystrokes are read raw and never echoed; piped input is read to its end. */
+export async function readPastedCode() {
+    const stdin = process.stdin;
+    let text = '';
+    if (stdin.isTTY) {
+        process.stderr.write('Paste the authorization code (input hidden), then press Enter: ');
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding('utf8');
+        await new Promise((resolve, reject) => {
+            const onData = (chunk) => {
+                for (const ch of chunk) {
+                    if (ch === '\r' || ch === '\n') {
+                        done();
+                        return resolve();
+                    }
+                    if (ch === '\u0003') {
+                        done();
+                        return reject(new Error('Cancelled.'));
+                    }
+                    if (ch === '\u007f' || ch === '\b')
+                        text = text.slice(0, -1);
+                    else if (ch >= ' ')
+                        text += ch;
+                }
+            };
+            const done = () => { stdin.off('data', onData); stdin.setRawMode(false); stdin.pause(); process.stderr.write('\n'); };
+            stdin.on('data', onData);
+        });
+    }
+    else {
+        for await (const chunk of stdin) {
+            text += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8');
+            if (text.length > 8192)
+                break;
+        }
+    }
+    return checkCode(text);
+}
+export function checkCode(raw) {
+    const code = raw.split(/\r?\n/)[0].trim();
+    if (!code || code.length > 512 || /[\u0000-\u001f\u007f]/.test(code))
+        throw new Error('Expected the authorization code on one line (at most 512 characters).');
+    return code;
+}
+const JOB_WAIT_DEFAULT_MS = 600_000;
+const parseLabel = (value, previous = {}) => {
+    const i = value.indexOf('=');
+    if (i < 1)
+        throw new Error('--label takes key=value.');
+    return { ...previous, [value.slice(0, i)]: value.slice(i + 1) };
+};
+const bounded = (value, name, min, max) => {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/.test(value) || Number(value) < min || Number(value) > max)
+        throw new Error(`${name} must be an integer from ${min} to ${max}.`);
+    return Number(value);
+};
+export function registerFlocks(program, client, emit, env = process.env, readCode = readPastedCode, isJson = () => false) {
+    const flocks = program.command('flocks').description('Flocks: your machines and cloud instances with a harness installed (nodes, harnesses, agents and runs)');
+    const secret = (name) => {
+        const value = env[name];
+        if (!value)
+            throw new Error(`Set ${name} in the environment; do not pass Flocks credentials as command-line arguments.`);
+        return value;
+    };
+    const show = async (run, pretty) => {
+        const data = await run(await client());
+        emit(data, () => (pretty ? pretty(data) : JSON.stringify(data, null, 2)));
+    };
+    // Account, grant, instance and job commands redact secret-looking fields; enrollment commands (join-token) must print theirs.
+    const showSafe = (run, pretty) => show(async (g) => scrub(await run(g)), pretty);
+    flocks.command('readiness').description('Check whether node enrollment is currently available').action(() => show(g => g.flocks.readiness.get()));
+    flocks.command('nodes').description('List your org nodes').action(() => show(g => g.flocks.nodes.list()));
+    const paging = (command) => command.option('--limit <n>', 'page size, 1–100').option('--cursor <cursor>', 'next_cursor from the previous page');
+    const query = (opts) => ({
+        ...(opts.limit === undefined ? {} : { limit: Number(opts.limit) }),
+        ...(opts.cursor === undefined ? {} : { cursor: opts.cursor }),
+        ...(opts.agentId === undefined ? {} : { agent_id: opts.agentId }),
+    });
+    paging(flocks.command('harnesses').description('List the harnesses each node reports, with version and readiness'))
+        .action((opts) => show(g => g.flocks.harnesses.list(query(opts))));
+    const agents = flocks.command('agents').description('Harness agents, and canonical agent execution (a_<ULID>; needs a signed-in session, not an API key)');
+    paging(agents.command('list').description('List agents')).action((opts) => show(g => g.flocks.agents.list(query(opts))));
+    agents.command('create <name> <harness>').description('Create an agent on a harness')
+        .option('--node <id>', 'pin the agent to one of your online nodes')
+        .action((name, harness, opts) => show(g => g.flocks.agents.create({ name, harness, ...(opts.node === undefined ? {} : { node_id: opts.node }) })));
+    agents.command('get <agent_id>').action((id) => show(g => g.flocks.agents.get(id)));
+    agents.command('execute <agent_id>').description('Execute a task on a canonical agent; the JSON request needs idempotency_key, task, driver, provider_account_id, target_roost and external_correlation')
+        .requiredOption('--body-file <path>', 'JSON request body, up to 64 KiB')
+        .action(async (id, opts) => { const body = await readFunctionJson(opts.bodyFile, 64 * 1024); return show(g => g.flocks.agents.execute(id, body)); });
+    agents.command('status <agent_id>').description('Observe the latest canonical execution').action((id) => show(g => g.flocks.agents.status(id)));
+    agents.command('cancel <agent_id>').description('Cancel the canonical execution admitted under an idempotency key')
+        .requiredOption('--idempotency-key <key>', 'the key the execution was admitted with')
+        .action((id, opts) => show(g => g.flocks.agents.cancel(id, opts.idempotencyKey)));
+    flocks.command('activity').description('Your recent agent sessions and events (needs a signed-in session, not an API key)').action(() => show(g => g.flocks.activity.get()));
+    const runs = flocks.command('runs').description('Recorded agent runs');
+    paging(runs.command('list').description('List runs').option('--agent-id <id>', 'only runs of this agent'))
+        .action((opts) => show(g => g.flocks.runs.list(query(opts))));
+    runs.command('get <run_id>').action((id) => show(g => g.flocks.runs.get(id)));
+    flocks.command('join-token').option('--ttl <seconds>', 'lifetime (60–600 seconds)', '600').action((opts) => {
+        const ttl = Number(opts.ttl);
+        if (!Number.isInteger(ttl) || ttl < 60 || ttl > 600)
+            throw new Error('TTL must be 60–600 seconds');
+        return show(g => g.flocks.joinTokens.create(ttl));
+    });
+    flocks.command('rename <id> <nickname>').action((id, nickname) => show(g => g.flocks.nodes.rename(id, nickname)));
+    flocks.command('revoke <id>').action((id) => show(g => g.flocks.nodes.revoke(id)));
+    flocks.command('enroll <name> <platform> <cpus>').description('Enroll this node with FLOCKS_JOIN_TOKEN from the environment').action((name, platform, cpus) => {
+        const cpu_count = Number(cpus);
+        if (!Number.isInteger(cpu_count) || cpu_count < 1 || cpu_count > 65536)
+            throw new Error('CPUs must be 1–65536');
+        const token = secret('FLOCKS_JOIN_TOKEN');
+        return show(g => g.flocks.nodes.enroll({ token, name, platform, cpu_count }));
+    });
+    flocks.command('heartbeat <id>').description('Send presence using FLOCKS_NODE_BINDING from the environment').action((id) => {
+        const binding = secret('FLOCKS_NODE_BINDING');
+        return show(g => g.flocks.nodes.heartbeat(id, binding));
+    });
+    flocks.command('exchange-join').description('Exchange FLOCKS_JOIN_TOKEN and FLOCKS_NODE_NONCE; save the returned key privately before activation').action(() => show(g => g.flocks.joinTokens.exchange({ token: secret('FLOCKS_JOIN_TOKEN'), node_nonce: secret('FLOCKS_NODE_NONCE') })));
+    flocks.command('activate <id> <name> <platform> <cpus>').description('Activate the saved node key with FLOCKS_NODE_NONCE').action((id, name, platform, cpus) => {
+        const cpu_count = Number(cpus);
+        if (!Number.isInteger(cpu_count) || cpu_count < 1 || cpu_count > 65536)
+            throw new Error('CPUs must be 1–65536');
+        return show(g => g.flocks.nodes.activate(id, { name, platform, cpu_count, node_nonce: secret('FLOCKS_NODE_NONCE') }));
+    });
+    flocks.command('rotate <id> <action>').description('prepare→persist→commit, or cancel; use saved FLOCKS_NODE_NONCE/FLOCKS_ROTATION_NONCE').action((id, action) => {
+        if (!['prepare', 'commit', 'cancel'].includes(action))
+            throw new Error('Action must be prepare, commit or cancel');
+        return show(g => g.flocks.nodes.rotateCredential(id, { action: action, node_nonce: secret('FLOCKS_NODE_NONCE'), operation_nonce: secret('FLOCKS_ROTATION_NONCE') }));
+    });
+    registerAccounts(flocks, client, showSafe, emit, env, readCode, isJson);
+}
+const ago = (t) => (typeof t === 'number' ? new Date(t * (t < 1e12 ? 1000 : 1)).toISOString().slice(0, 19) + 'Z' : '');
+const items = (data) => (Array.isArray(data) ? data : Array.isArray(data?.items) ? data.items : []);
+const accountRows = (data) => table(items(data).map(a => ({ ...a, owner: a.granted ? `${a.owner_org} (granted)` : 'you' })), ['id', 'provider', 'label', 'auth_kind', 'identity', 'status', 'owner']);
+const jobText = (job) => {
+    const t = job.totals ?? {};
+    const head = `${safe(job.id)}  ${safe(job.kind)}  ${safe(job.state)}` + (job.account_id ? `  account ${safe(job.account_id)}` : '') + `  succeeded ${t.succeeded ?? 0}/${(job.items ?? []).length}`
+        + (t.failed ? `, failed ${t.failed}` : '') + (t.timed_out ? `, timed out ${t.timed_out}` : '') + (t.rolled_back ? `, rolled back ${t.rolled_back}` : '') + (t.unsupported ? `, unsupported ${t.unsupported}` : '');
+    const rows = (job.items ?? []).map((i) => ({ ...i, login: undefined }));
+    const logins = (job.items ?? []).filter((i) => i.login).map((i) => i.login.url && i.login.code
+        ? `Open ${safe(i.login.url)} and enter code ${safe(i.login.code)}  (instance ${safe(i.instance_id)})`
+        : i.login.url
+            ? `Open ${safe(i.login.url)}, sign in, then send the code it shows with: genesis flocks jobs login-input ${safe(job.id)} --instance ${safe(i.instance_id)}`
+            : `Waiting for the sign-in code from instance ${safe(i.instance_id)}...`);
+    return [head, rows.length ? table(rows, ['instance_id', 'state', 'previous_account_id', 'identity', 'error_code']) : '', ...logins].filter(Boolean).join('\n');
+};
+const nodeRows = (data) => table(items(data).map(n => ({
+    id: n.id, nickname: n.nickname, state: n.state, flock: n.labels?.flock ?? '',
+    labels: Object.entries(n.labels ?? {}).filter(([k]) => k !== 'flock').map(([k, v]) => `${k}=${v}`),
+    accounts: (n.accounts ?? []).map((a) => `${a.provider}:${a.identity ?? a.account_id ?? 'none'}`),
+})), ['id', 'nickname', 'state', 'flock', 'labels', 'accounts']);
+function registerAccounts(flocks, client, show, emit, env, readCode, isJson) {
+    const interval = Number(env.FLOCKS_POLL_INTERVAL_MS) > 0 ? Number(env.FLOCKS_POLL_INTERVAL_MS) : 2000;
+    const finish = (job) => {
+        if (job.state === 'partial' || job.state === 'failed')
+            throw new Error(`Job ${safe(job.id)} finished ${safe(job.state)}: ${job.totals?.failed ?? 0} failed, ${job.totals?.timed_out ?? 0} timed out, ${job.totals?.rolled_back ?? 0} rolled back. Exit status 1.`);
+    };
+    /** Show the job the service accepted; with --wait, follow it to the end and fail the command when any instance failed. */
+    const showJob = async (start, wait) => {
+        const g = await client();
+        let job = scrub(await start(g));
+        if (wait && job.state === 'running')
+            job = scrub(await g.flocks.jobs.wait(job.id, { intervalMs: interval, timeoutMs: JOB_WAIT_DEFAULT_MS }));
+        emit(job, () => jobText(job));
+        if (wait)
+            finish(job);
+    };
+    const withJobId = async (g, r, wait) => {
+        // delete and revoke answer { account|grant, job_id }
+        if (!wait || !r?.job_id)
+            return r;
+        const job = await g.flocks.jobs.wait(r.job_id, { intervalMs: interval, timeoutMs: JOB_WAIT_DEFAULT_MS });
+        return { ...r, job };
+    };
+    flocks.command('providers').description('Inference providers, the login kinds each supports, and which plans fit sharing one login').action(() => show(g => g.flocks.providers.list(), data => items(data).map(p => `${safe(p.id)}  ${safe(p.display_name)}  (${(p.auth_kinds ?? []).map(safe).join(', ')})\n  ${safe(p.plan_guidance)}`).join('\n')));
+    const accounts = flocks.command('accounts').description('Inference accounts: one login (or API key) many instances can run under');
+    accounts.command('list').description('Accounts your org owns plus accounts granted to it')
+        .option('--provider <id>', 'only this provider').option('--limit <n>', 'page size, 1-100').option('--cursor <cursor>', 'next_cursor from the previous page')
+        .action((o) => show(g => g.flocks.accounts.list({
+        ...(o.provider ? { provider: o.provider } : {}), ...(o.limit ? { limit: bounded(o.limit, '--limit', 1, 100) } : {}), ...(o.cursor ? { cursor: o.cursor } : {}),
+    }), accountRows));
+    accounts.command('add <provider> <label>').description('Add an account. subscription_oauth accounts are signed in afterwards with `accounts login`; api_key accounts take a secret reference only')
+        .option('--auth-kind <kind>', 'subscription_oauth or api_key', 'subscription_oauth')
+        .option('--api-key-secret-ref <ref>', 'api_key accounts: the name of a key your org already holds in Blinds (NAME or blinds:NAME)')
+        .addOption(new Option('--api-key <value>').hideHelp())
+        .action((provider, label, o) => {
+        if (o.apiKey !== undefined)
+            throw new Error('Raw API keys are never accepted on the command line. Store the key in Blinds or Secret Manager and pass --api-key-secret-ref.');
+        if (!['subscription_oauth', 'api_key'].includes(o.authKind))
+            throw new Error('--auth-kind must be subscription_oauth or api_key.');
+        if (o.authKind === 'api_key' && !o.apiKeySecretRef)
+            throw new Error('api_key accounts need --api-key-secret-ref (the name of a Blinds variable your org already holds).');
+        if (o.authKind !== 'api_key' && o.apiKeySecretRef)
+            throw new Error('--api-key-secret-ref is only for --auth-kind api_key.');
+        const ref = o.apiKeySecretRef === undefined ? undefined : checkSecretRef(o.apiKeySecretRef);
+        return show(g => g.flocks.accounts.create({ provider, label, auth_kind: o.authKind, ...(ref ? { api_key_secret_ref: ref } : {}) }), a => accountRows([a]));
+    });
+    accounts.command('get <account_id>').description('One account, with the number of instances bound to it')
+        .action((id) => show(g => g.flocks.accounts.get(id), a => accountRows([a]) + `\nbound instances: ${a.bound_instances ?? 0}`));
+    accounts.command('login <account_id>').description('Sign an account in from one of your instances; prints the device url and code (only you receive them)')
+        .requiredOption('--instance <id>', 'the instance that runs the provider login')
+        .option('--timeout <seconds>', 'how long to wait for the code', '60')
+        .action(async (id, o) => {
+        const g = await client();
+        const seconds = bounded(o.timeout, '--timeout', 0, 600);
+        let job = scrub(await g.flocks.accounts.login(id, o.instance));
+        const deadline = Date.now() + seconds * 1000;
+        const awaiting = (j) => (j.items ?? []).find((i) => i.login?.url && !i.login.code && i.state !== 'succeeded' && i.state !== 'failed');
+        while (job.state === 'running' && !(job.items ?? []).some((i) => i.login?.url) && Date.now() < deadline) {
+            await new Promise(r => setTimeout(r, interval));
+            job = scrub(await g.flocks.jobs.get(job.id));
+        }
+        const waiting = job.state === 'running' ? awaiting(job) : undefined;
+        if (waiting) {
+            // The provider printed a URL and waits for the pasted code: show the URL, then read the code without echoing it.
+            if (!isJson())
+                emit(job, () => jobText(job)); // --json prints one document, after the code is sent
+            const code = await readCode();
+            await g.flocks.jobs.submitLoginInput(job.id, waiting.instance_id, code);
+            job = scrub(await g.flocks.jobs.get(job.id));
+            emit(job, () => `Code sent.\n` + jobText(job) + (job.state === 'running' ? `\nFinish with: genesis flocks jobs get ${safe(job.id)} --wait` : ''));
+            return;
+        }
+        emit(job, () => jobText(job) + (job.state === 'running' ? `\nFinish with: genesis flocks jobs get ${safe(job.id)} --wait` : ''));
+    });
+    accounts.command('remove <account_id>').description('Sign the account out of every bound instance, then revoke its credential')
+        .option('--wait', 'follow the logout job to the end')
+        .action((id, o) => show(async (g) => withJobId(g, await g.flocks.accounts.delete(id), o.wait), r => `account ${safe(r.account?.id)} ${safe(r.account?.status)}; logout job ${safe(r.job_id)}` + (r.job ? '\n' + jobText(r.job) : '')));
+    const grants = flocks.command('grants').description('Let another org bind its instances to one of your accounts');
+    grants.command('list').description('Grants you issued or received')
+        .option('--direction <dir>', 'issued or received', 'issued').option('--account <id>', 'only this account')
+        .action((o) => {
+        if (!['issued', 'received'].includes(o.direction))
+            throw new Error('--direction must be issued or received.');
+        return show(g => g.flocks.grants.list({ direction: o.direction, ...(o.account ? { account_id: o.account } : {}) }), d => table(items(d).map(x => ({ ...x, created: ago(x.created_at), revoked: ago(x.revoked_at) })), ['id', 'account_id', 'owner_org', 'grantee_org', 'status', 'note', 'created', 'revoked']));
+    });
+    grants.command('add <account_id> <grantee_org>').description('Grant an account you own to another org')
+        .option('--note <text>')
+        .action((id, org, o) => show(g => g.flocks.grants.create(id, { grantee_org_id: org, ...(o.note ? { note: o.note } : {}) })));
+    grants.command('revoke <grant_id>').description('Revoke a grant: new runs stop at once and grantee instances are signed out and wiped')
+        .option('--wait', 'follow the logout job to the end')
+        .action((id, o) => show(async (g) => withJobId(g, await g.flocks.grants.revoke(id), o.wait), r => `grant ${safe(r.grant?.id)} ${safe(r.grant?.status)}; logout job ${safe(r.job_id)}` + (r.job ? '\n' + jobText(r.job) : '')));
+    const instances = flocks.command('instances').description('Your instances and the inference account each runs under');
+    instances.command('list').description('Instances with their flock, labels and active accounts').action(() => show(g => g.flocks.nodes.list(), nodeRows));
+    instances.command('label <instance_id> [labels...]').description('Set labels (key=value) on an instance; the key flock groups instances. --remove drops a key')
+        .option('--remove <key...>', 'label keys to remove')
+        .action((id, pairs, o) => show(async (g) => {
+        const nodes = (await g.flocks.nodes.list());
+        const current = nodes.find(n => n.id === id);
+        if (!current)
+            throw new Error(`No instance ${id} in your org.`);
+        let labels = { ...(current.labels ?? {}) };
+        for (const p of pairs)
+            labels = parseLabel(p, labels);
+        for (const k of o.remove ?? [])
+            delete labels[k];
+        return g.flocks.nodes.update(id, { labels });
+    }, n => nodeRows([n])));
+    instances.command('account <instance_id>').description('Which account is bound to an instance, per provider')
+        .action((id) => show(g => g.flocks.instances.getAccount(id), d => table((d.accounts ?? []).map((a) => ({ ...a, updated: ago(a.updated_at) })), ['provider', 'account_id', 'identity', 'auth_state', 'binding_state', 'desired_account_id', 'updated'])));
+    const selecting = (command) => command
+        .option('--flock <name>', 'every instance in this flock (label flock)').option('--label <k=v>', 'instances carrying this label (repeatable)', parseLabel)
+        .option('--from-account <id>', 'instances currently bound to this account')
+        .option('--concurrency <n>', 'instances processed at once, 1-20 (bulk)')
+        .option('--wait', 'follow the job to the end; exits non-zero if any instance failed');
+    const selector = (ids, o) => {
+        const sel = { ...(ids.length ? { instance_ids: ids } : {}), ...(o.flock ? { flock: o.flock } : {}), ...(o.label ? { labels: o.label } : {}), ...(o.fromAccount ? { from_account_id: o.fromAccount } : {}) };
+        if (!Object.keys(sel).length)
+            throw new Error('Name instances, or select with --flock, --label or --from-account.');
+        return sel;
+    };
+    selecting(instances.command('switch-account [instance_ids...]').description('Switch instances to an account: drain, install, verify identity, swap (a failed verify rolls back)')
+        .requiredOption('--account <id>', 'the account to switch to').option('--provider <id>', 'provider when the account spans several')
+        .option('--force', 'cancel in-flight runs instead of waiting for them').option('--drain-timeout <seconds>', 'wait for in-flight runs, default 120'))
+        .action((ids, o) => {
+        const drain = bounded(o.drainTimeout, '--drain-timeout', 0, 3600);
+        const concurrency = bounded(o.concurrency, '--concurrency', 1, 20);
+        const extra = { ...(o.force ? { force: true } : {}), ...(drain === undefined ? {} : { drain_timeout_secs: drain }) };
+        const single = ids.length === 1 && !o.flock && !o.label && !o.fromAccount && concurrency === undefined;
+        return showJob(g => single
+            ? g.flocks.instances.switchAccount(ids[0], { account_id: o.account, ...(o.provider ? { provider: o.provider } : {}), ...extra })
+            : g.flocks.instances.bulkSwitchAccount({ selector: selector(ids, o), account_id: o.account, ...(concurrency === undefined ? {} : { concurrency }), ...extra }), o.wait);
+    });
+    selecting(instances.command('logout [instance_ids...]').description('Sign instances out of a provider account (files deleted; the provider login itself is untouched)')
+        .requiredOption('--provider <id>', 'the provider to sign out of')
+        .option('--force', 'cancel in-flight runs instead of waiting for them'))
+        .action((ids, o) => {
+        const concurrency = bounded(o.concurrency, '--concurrency', 1, 20);
+        const single = ids.length === 1 && !o.flock && !o.label && !o.fromAccount && concurrency === undefined;
+        return showJob(g => single
+            ? g.flocks.instances.logout(ids[0], o.provider, o.force)
+            : g.flocks.instances.bulkLogout({ selector: selector(ids, o), provider: o.provider, ...(o.force ? { force: true } : {}), ...(concurrency === undefined ? {} : { concurrency }) }), o.wait);
+    });
+    const jobs = flocks.command('jobs').description('Asynchronous account jobs (login, switch, sign-out)');
+    jobs.command('get <job_id>').description('A job and its per-instance results')
+        .option('--wait', 'poll until the job is no longer running; exits non-zero if any instance failed')
+        .action((id, o) => showJob(g => g.flocks.jobs.get(id), o.wait));
+    jobs.command('login-input <job_id>').description('Send the authorization code a headless sign-in is waiting for; the code is read from stdin, never from arguments')
+        .requiredOption('--instance <id>', 'the instance running the sign-in')
+        .action(async (id, o) => {
+        const code = await readCode();
+        await show(g => g.flocks.jobs.submitLoginInput(id, o.instance, code), () => 'Code sent. Follow the job with: genesis flocks jobs get ' + safe(id) + ' --wait');
+    });
+}

package/dist/function-input.d.ts

@@ -0,0 +1,3 @@
+export declare function readFunctionFile(path: string, limit: number): Promise<Uint8Array>;
+export declare function readFunctionJson(path: string, limit: number): Promise<Record<string, unknown>>;
+export declare function writeFunctionOutput(path: string, bytes: Uint8Array): Promise<void>;

package/dist/function-input.js

@@ -0,0 +1,49 @@
+import { open, writeFile } from 'node:fs/promises';
+export async function readFunctionFile(path, limit) {
+    let file;
+    try {
+        file = await open(path, 'r');
+    }
+    catch {
+        throw new Error('Could not open the function input file. Check its path and permissions.');
+    }
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > limit)
+            throw new Error('Choose a regular function input file within the documented size limit.');
+        const bytes = new Uint8Array(limit + 1);
+        let size = 0;
+        for (;;) {
+            const { bytesRead } = await file.read(bytes, size, bytes.length - size, null);
+            if (!bytesRead)
+                break;
+            size += bytesRead;
+            if (size > limit)
+                throw new Error('Function input file exceeds the documented size limit.');
+        }
+        return bytes.slice(0, size);
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function readFunctionJson(path, limit) {
+    const bytes = await readFunctionFile(path, limit);
+    try {
+        const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error();
+        return value;
+    }
+    catch {
+        throw new Error('Function request file must contain a JSON object. No input value is echoed.');
+    }
+}
+export async function writeFunctionOutput(path, bytes) {
+    try {
+        await writeFile(path, bytes, { flag: 'wx', mode: 0o600 });
+    }
+    catch {
+        throw new Error('Could not create the output file. Choose a new path with write permission. Existing files are preserved.');
+    }
+}

package/dist/henry.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+import type { Genesis } from '@onesi/genesis';
+/** `line` prints one NDJSON line (henry events --follow); `signal` stops a follow. */
+export declare function addHenryCommands(program: Command, client: () => Promise<Genesis>, output: (value: unknown) => void, stream?: {
+    line: (text: string) => void;
+    signal?: AbortSignal;
+}): void;

package/dist/henry.js

@@ -0,0 +1,85 @@
+import { readFoundryKey } from './fleets.js';
+const RUN_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const DELIVERIES = ['steer', 'queue', 'interrupt'];
+/** `line` prints one NDJSON line (henry events --follow); `signal` stops a follow. */
+export function addHenryCommands(program, client, output, stream = { line: text => process.stdout.write(`${text}\n`) }) {
+    const number = (value, name) => {
+        if (value === undefined)
+            return undefined;
+        if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)))
+            throw new Error(`${name} must be a non-negative integer`);
+        return Number(value);
+    };
+    const henry = program.command('henry').description('Henry: agent runtime, live activity and approvals');
+    henry.command('config').action(async () => output(await (await client()).henry.config()));
+    henry.command('credential').description('Read a Foundry API key from stdin and encrypt it in Genesis KMS')
+        .action(async () => {
+        const apiKey = await readFoundryKey();
+        output(await (await client()).henry.credential(apiKey));
+    });
+    henry.command('models').description('List the Foundry models the stored organization key can run').action(async () => output(await (await client()).henry.models()));
+    henry.command('runs').option('--page-token <token>').action(async (options) => output(await (await client()).henry.runs.list(options.pageToken)));
+    henry.command('run').requiredOption('--model <model>').requiredOption('--task <text>').option('--run-id <uuid>', 'UUIDv4 for concurrent activity polling')
+        .action(async (options) => output(await (await client()).henry.runs.create({ model: options.model, task: options.task, ...(options.runId ? { run_id: options.runId } : {}) })));
+    henry.command('get <run_id>').action(async (runId) => output(await (await client()).henry.runs.get(runId)));
+    henry.command('events <run_id>').description('Page a run\'s activity events, or follow them live with --follow')
+        .option('--after-seq <n>', 'return events after this sequence number').option('--limit <n>', 'page size, 1-500')
+        .option('--follow', 'stream events as NDJSON lines until the run ends (reconnects every 120 s stream)')
+        .action(async (runId, options) => {
+        const afterSeq = number(options.afterSeq, '--after-seq'), limit = number(options.limit, '--limit');
+        if (options.follow) {
+            if (limit !== undefined)
+                throw new Error('--limit pages events; --follow streams them');
+            const events = (await client()).henry.runs.streamEvents(runId, { ...(afterSeq === undefined ? {} : { afterSeq }), ...(stream.signal ? { signal: stream.signal } : {}) });
+            for await (const { event, data } of events)
+                stream.line(JSON.stringify({ event, ...data }));
+            return;
+        }
+        output(await (await client()).henry.runs.events(runId, { ...(afterSeq === undefined ? {} : { after_seq: afterSeq }), ...(limit === undefined ? {} : { limit }) }));
+    });
+    henry.command('message <run_id>').description('Send a message into a run: steer, queue (default) or interrupt')
+        .requiredOption('--text <text>').option('--delivery <delivery>', 'steer, queue or interrupt')
+        .action(async (runId, options) => {
+        if (options.delivery !== undefined && !DELIVERIES.includes(options.delivery))
+            throw new Error('--delivery must be steer, queue or interrupt');
+        output(await (await client()).henry.runs.message(runId, { text: options.text, ...(options.delivery ? { delivery: options.delivery } : {}) }));
+    });
+    henry.command('fork <run_id>').description('Start a new run from a past turn (0 = the original task; default the latest, which needs --text)')
+        .option('--turn <n>', 'turn to fork from').option('--text <text>', 'user message to append').option('--model <model>').option('--run-id <uuid>', 'UUIDv4 for the new run (idempotency key)')
+        .action(async (runId, options) => {
+        const turn = number(options.turn, '--turn');
+        if (options.runId !== undefined && !RUN_ID.test(options.runId))
+            throw new Error('--run-id must be a lowercase UUIDv4');
+        output(await (await client()).henry.runs.fork(runId, { ...(turn === undefined ? {} : { turn }), ...(options.text === undefined ? {} : { text: options.text }),
+            ...(options.model === undefined ? {} : { model: options.model }), ...(options.runId === undefined ? {} : { run_id: options.runId }) }));
+    });
+    henry.command('replay <run_id>').description('Read every event of a run and fold them into turns (each turn\'s inputs and answer)')
+        .action(async (runId) => output(await (await client()).henry.runs.replay(runId, stream.signal ? { signal: stream.signal } : {})));
+    henry.command('delete <run_id>').description('Delete a finished run (cancel active runs first)').action(async (runId) => output(await (await client()).henry.runs.delete(runId)));
+    henry.command('receipt-key').description('Print the current Henry receipt verification key').action(async () => output(await (await client()).henry.receipts.verificationKey()));
+    henry.command('blinds-proxy').description('Send an HTTPS request through the organization\'s Blinds machine')
+        .requiredOption('--method <method>', 'GET, POST, PUT, PATCH or DELETE').requiredOption('--url <https-url>')
+        .option('--header <name:value...>', 'request header, repeatable').option('--body <text>').option('--request-id <id>')
+        .action(async (options) => {
+        const headers = {};
+        for (const entry of options.header ?? []) {
+            const at = String(entry).indexOf(':');
+            if (at < 1)
+                throw new Error('--header must be name:value');
+            headers[entry.slice(0, at).trim()] = entry.slice(at + 1).trim();
+        }
+        output(await (await client()).henry.blinds.proxy({ method: String(options.method).toUpperCase(), url: options.url,
+            ...(Object.keys(headers).length ? { headers } : {}), ...(options.body === undefined ? {} : { body: options.body }), ...(options.requestId ? { request_id: options.requestId } : {}) }));
+    });
+    henry.command('command <run_id> <action>').option('--text <text>')
+        .action(async (runId, action, options) => {
+        if (!['pause', 'resume', 'cancel', 'input'].includes(action))
+            throw new Error('Action must be pause, resume, cancel or input');
+        output(await (await client()).henry.runs.command(runId, action, options.text));
+    });
+    henry.command('approval <run_id> <approval_id> <decision>').action(async (runId, approvalId, decision) => {
+        if (!['approve', 'reject'].includes(decision))
+            throw new Error('Decision must be approve or reject');
+        output(await (await client()).henry.runs.approval(runId, approvalId, decision));
+    });
+}

package/dist/hives-coverage.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from 'commander';
+import { type Genesis, type OperationId } from '@onesi/genesis';
+/** `genesis hives <words>` -> Hives operation. Positional arguments are the path parameters, query
+ * parameters become options, a JSON body comes from --body-file. Groups that already exist
+ * (functions, deployments, environment, domains, logs) are extended, never replaced. */
+export declare const HIVES_COVERAGE_COMMANDS: Record<string, OperationId>;
+/** Register after every other `hives` group so existing groups are found and extended. */
+export declare function registerHivesCoverage(hives: Command, deps: {
+    client: () => Promise<Genesis>;
+    emit: (data: unknown, pretty: () => string) => void;
+    readRequest?: (path: string, limit: number) => Promise<unknown>;
+}): void;

package/dist/hives-coverage.js

@@ -0,0 +1,116 @@
+import { hivesSseWindow, idempotencyHeaders, operationTable } from '@onesi/genesis';
+import { readFunctionJson } from './function-input.js';
+/** `genesis hives <words>` -> Hives operation. Positional arguments are the path parameters, query
+ * parameters become options, a JSON body comes from --body-file. Groups that already exist
+ * (functions, deployments, environment, domains, logs) are extended, never replaced. */
+export const HIVES_COVERAGE_COMMANDS = {
+    'flights list': 'hives_list_flights',
+    'flights create': 'hives_create_flight',
+    'flights get': 'hives_get_flight',
+    'flights files': 'hives_list_flight_files',
+    'flights read-file': 'hives_read_flight_file',
+    'flights processes': 'hives_list_flight_processes',
+    'flights env': 'hives_list_flight_env',
+    'flights debug-metrics': 'hives_list_flight_debug_metrics',
+    'functions logs': 'hives_query_function_logs',
+    'deployments stream-logs': 'hives_stream_deployment_logs',
+    'logs aggregate': 'hives_aggregate_logs',
+    'logs search': 'hives_search_logs',
+    'environment values': 'hives_get_project_env',
+    'environment set': 'hives_set_project_env',
+    'environment delete': 'hives_delete_project_env',
+    'domains get': 'hives_get_domain',
+    'domains delete': 'hives_delete_domain',
+    'domains verification-record': 'hives_get_verification_record',
+};
+const DESCRIPTIONS = {
+    flights: 'Flights: WASM HTTP workloads served at their own address',
+    logs: 'Project logs',
+    domains: 'Custom domains for a project',
+};
+const BODY_LIMIT = 1024 * 1024;
+const flag = (name) => name.replace(/_/g, '-').toLowerCase();
+const key = (name) => flag(name).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+const integer = (value, name, max) => {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/.test(value) || Number(value) < 1 || Number(value) > max)
+        throw new Error(`${name} must be an integer from 1 to ${max}.`);
+    return Number(value);
+};
+const subcommand = (parent, name) => parent.commands.find((c) => c.name() === name) ?? parent.command(name).description(DESCRIPTIONS[name] ?? name);
+function queryValue(schema, value) {
+    const type = schema?.type;
+    if (type === 'integer') {
+        if (!/^\d+$/.test(value))
+            throw new Error(`Expected an integer, got "${value}".`);
+        return Number(value);
+    }
+    if (type === 'boolean') {
+        if (value !== 'true' && value !== 'false')
+            throw new Error(`Expected true or false, got "${value}".`);
+        return value === 'true';
+    }
+    return value;
+}
+/** Register after every other `hives` group so existing groups are found and extended. */
+export function registerHivesCoverage(hives, deps) {
+    const read = deps.readRequest ?? readFunctionJson;
+    const output = (data) => deps.emit(data ?? { ok: true }, () => JSON.stringify(data ?? { ok: true }, null, 2));
+    for (const [words, id] of Object.entries(HIVES_COVERAGE_COMMANDS)) {
+        const op = operationTable[id];
+        const parts = words.split(' ');
+        let parent = hives;
+        for (const part of parts.slice(0, -1))
+            parent = subcommand(parent, part);
+        const properties = (op.inputSchema.properties ?? {});
+        const required = op.inputSchema.required;
+        if (id === 'hives_delete_project_env') {
+            // The body is a JSON array of names: take them as arguments instead of a file.
+            parent.command(`${parts.at(-1)} <project_id> <names...>`).description(`${op.summary} (${op.method} ${op.path})`)
+                .action(async (project, names) => output(await (await deps.client()).request(id, { project_id: project, body: names })));
+            continue;
+        }
+        const command = parent.command([parts.at(-1), ...op.pathParams.map((p) => `<${p}>`)].join(' '))
+            .description(`${op.summary} (${op.method} ${op.path})`);
+        for (const q of op.queryParams) {
+            const description = properties[q]?.description;
+            command[required.includes(q) ? 'requiredOption' : 'option'](`--${flag(q)} <value>`, description);
+        }
+        if (op.hasBody)
+            command[required.includes('body') ? 'requiredOption' : 'option']('--body-file <path>', 'JSON request body, up to 1 MiB');
+        if (op.idempotencyKey)
+            command.option('--idempotency-key <key>', 'Required when slug is omitted; reuse it to get the original result');
+        if (op.stream) {
+            command.option('--max-events <number>', 'stop after this many events (1-1000, default 100)')
+                .option('--seconds <number>', 'stop after this many seconds (1-15, default 10)');
+        }
+        if (id === 'hives_get_project_env')
+            command.option('--stdout', 'write every decrypted value to stdout (avoid retained output)');
+        command.action(async (...args) => {
+            const options = args[op.pathParams.length];
+            if (id === 'hives_get_project_env' && !options.stdout)
+                throw new Error('Reading every environment value requires --stdout. Avoid logging or retaining the plaintext.');
+            const input = Object.fromEntries(op.pathParams.map((p, i) => [p, args[i]]));
+            for (const q of op.queryParams) {
+                const value = options[key(q)];
+                if (value === undefined)
+                    continue;
+                input[q] = typeof value === 'boolean' ? value : queryValue(properties[q], value);
+            }
+            if (typeof options.bodyFile === 'string')
+                input.body = await read(options.bodyFile, BODY_LIMIT);
+            const client = await deps.client();
+            if (op.stream) {
+                const response = await client.raw(id, input, { headers: { accept: 'text/event-stream' } });
+                output(await hivesSseWindow(response, {
+                    maxEvents: integer(options.maxEvents, '--max-events', 1000),
+                    seconds: integer(options.seconds, '--seconds', 15),
+                }));
+                return;
+            }
+            const headers = idempotencyHeaders(id, options.idempotencyKey);
+            output(await client.request(id, input, { headers }));
+        });
+    }
+}

package/dist/hives-marketplace.d.ts

@@ -0,0 +1,10 @@
+import { Command } from 'commander';
+import type { Genesis } from '@onesi/genesis';
+type Deps = {
+    client: () => Promise<Genesis>;
+    emit: (data: unknown, pretty: () => string) => void;
+    readRequest?: (path: string, limit: number) => Promise<Record<string, unknown>>;
+};
+/** Environment values belong in a bounded private JSON file, never command-line options. */
+export declare function registerHivesMarketplace(hives: Command, deps: Deps): void;
+export {};