@onesi/genesis-cli 0.1.13 → 0.2.0

package/README.md

@@ -3,9 +3,36 @@
 `genesis`, the OneOS command line. It works against the Genesis API at `https://os.one.ml/api`.
 
 ```sh
-npx -y @onesi/genesis-cli@0.1.13 --help
+npx -y @onesi/genesis-cli@0.2.0 --help
 ```
 
+## First run
+
+```sh
+npx -y @onesi/genesis-cli    # or: npm i -g @onesi/genesis-cli, then genesis
+```
+
+On a terminal, the first `genesis` opens `genesis setup`: six steps, about a minute, each skippable and resumable.
+
+![genesis setup: the ONE logotype wakes as One's eye, then sign-in, your project, your agents and a live status call](../../docs/media/genesis-setup/genesis-setup.gif)
+
+1. **Sign in with One**, in this browser or with a code on any device.
+2. **Organization, project and environment**, picked from your own (Sandbox).
+3. **An API key** for CI and other machines, only if you want one: read-only, your access, or chosen scopes; shown once or kept in Blinds.
+4. **Your agents**: the Genesis MCP server added to Claude Code, Claude Desktop, Cursor, VS Code, Windsurf or Codex. You see every file or command first; JSON files keep their other servers and a `.genesis-backup` copy.
+5. **A first live call**: every service's state and latency from the gateway.
+6. **What to do next.**
+
+Enter takes the default, `s` skips, Ctrl-C pauses. `genesis setup` picks up at the first open step, `genesis setup <step>` redoes one (`signin`, `context`, `key`, `mcp`, `try`, `next`), and `genesis setup --restart` starts over. `genesis setup --json` reports progress for scripts. Progress lives in `~/.config/genesis/setup.json` (no credentials; the login stays in the OS keychain).
+
+Setup draws with what your terminal can do, and asks it first: truecolor with edges blended against your real background (or your own ink when the terminal does not say), synchronized output, OSC 8 links, tab progress, and a desktop notification when sign-in finishes while you are in the browser. It is still with `NO_COLOR`, `TERM=dumb`, in CI or a pipe, with `--no-animation` or `GENESIS_REDUCED_MOTION=1`, and when your system asks for reduced motion. `--screen-reader` (or `GENESIS_SCREEN_READER=1`, or VoiceOver running) gives linear output with numbered choices.
+
+| Signing in with a code | Still, with `NO_COLOR` and `--no-animation` |
+|---|---|
+| ![Device sign-in beside One's eye](../../docs/media/genesis-setup/genesis-setup-device.gif) | ![The same setup, still and uncoloured](../../docs/media/genesis-setup/genesis-setup-still.gif) |
+
+The recordings were made with `--screencast` against the live services; `docs/media/genesis-setup/*.tape` are the [VHS](https://github.com/charmbracelet/vhs) scripts. `--sound` adds a soft chime. `--screencast` (or `GENESIS_SCREENCAST=1`) masks account names, emails and IDs, for recording demos. Only `genesis setup` and a bare `genesis` load any of this; other commands start exactly as fast as before.
+
 ## Sign in
 
 ```sh
@@ -27,7 +54,7 @@ genesis status                      # live state of each service
 genesis hives projects list
 genesis hives projects create my-app --kind worker
 genesis hives projects delete prj_...
-genesis --json silos projects list  # machine-readable output; errors include code, required_scope and request_id
+genesis --json silos instances list  # machine-readable output; errors include code, required_scope and request_id
 ```
 
 `genesis <service> --help` lists every command for a service. `--base-url` or `GENESIS_BASE_URL` overrides the gateway, and `https://console.life.one/api` is an alias. Requires Node.js 20.19 or later.

package/dist/beacons.js

@@ -15,6 +15,26 @@ export function registerBeacons(program, client, emit) {
         const result = await (await client()).beacons.fleets.peers(id);
         emit(result, () => JSON.stringify(result, null, 2));
     });
+    fleets.command('get <fleet-id>').description('Read one fleet in the current authorized scope').action(async (id) => {
+        const result = await (await client()).beacons.fleets.get(id);
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    fleets.command('dns <fleet-id>').description('Mesh DNS map: one A record per live peer').action(async (id) => {
+        const result = await (await client()).beacons.fleets.dns(id);
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    fleets.command('discovery <fleet-id>').description("Mesh discovery map: live peers' public keys, DNS and relay map").action(async (id) => {
+        const result = await (await client()).beacons.fleets.discovery(id);
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    fleets.command('client-profile <fleet-id> <platform>').description('beacons-agent profile: linux, macos, windows, ios or android').action(async (id, platform) => {
+        const result = await (await client()).beacons.fleets.clientProfile(id, platform);
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    fleets.command('wireguard-config <fleet-id> <peer-id>').description("One peer's WireGuard config: other peers' public keys, never a private key").action(async (id, peer) => {
+        const result = await (await client()).beacons.fleets.wireguardConfig(id, peer);
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
     const policy = fleets.command('policy').description('Future enrollment admission; does not grant permissions or revoke devices');
     policy.command('get <fleet-id>').action(async (id) => {
         const result = await (await client()).beacons.fleets.policy.get(id);
@@ -33,6 +53,54 @@ export function registerBeacons(program, client, emit) {
         });
         emit(result, () => JSON.stringify(result, null, 2));
     });
+    const resources = fleets.command('resources').description('Fleet configuration records: gateways, private-gateways, sims (configuration only)');
+    const family = (value) => {
+        if (!['gateways', 'private-gateways', 'sims'].includes(value))
+            throw new Error('Family must be gateways, private-gateways or sims.');
+        return value;
+    };
+    const config = (value) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(value);
+        }
+        catch {
+            throw new Error('--config must be a JSON object.');
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            throw new Error('--config must be a JSON object.');
+        return parsed;
+    };
+    resources.command('list <fleet-id> <family>').description('List the fleet\'s records of one family').action(async (id, kind) => {
+        const result = await (await client()).beacons.fleets.resources.list(id, family(kind));
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    resources.command('create <fleet-id> <family>').description('Create one record; not idempotent')
+        .requiredOption('--name <name>', 'Record name, at most 128 UTF-8 bytes')
+        .requiredOption('--status <status>', 'active, inactive, disabled or pending')
+        .option('--config <json>', 'Family config object, e.g. \'{"type":"relay","routes":["10.0.0.0/24"]}\'', '{}')
+        .action(async (id, kind, opts) => {
+        const result = await (await client()).beacons.fleets.resources.create(id, family(kind), { name: opts.name, status: opts.status, config: config(opts.config) });
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    resources.command('update <fleet-id> <family> <resource-id>').description('Replace the given fields of one record')
+        .option('--name <name>', 'New name').option('--status <status>', 'active, inactive, disabled or pending')
+        .option('--config <json>', 'Replacement family config object')
+        .action(async (id, kind, resourceId, opts) => {
+        if (opts.name === undefined && opts.status === undefined && opts.config === undefined)
+            throw new Error('Supply --name, --status or --config.');
+        const result = await (await client()).beacons.fleets.resources.update(id, family(kind), resourceId, {
+            ...(opts.name === undefined ? {} : { name: opts.name }), ...(opts.status === undefined ? {} : { status: opts.status }),
+            ...(opts.config === undefined ? {} : { config: config(opts.config) })
+        });
+        emit(result, () => JSON.stringify(result, null, 2));
+    });
+    resources.command('delete <fleet-id> <family> <resource-id>').description('Delete one configuration record')
+        .action(async (id, kind, resourceId) => {
+        await (await client()).beacons.fleets.resources.delete(id, family(kind), resourceId);
+        const result = { deleted: resourceId };
+        emit(result, () => `Deleted ${resourceId}`);
+    });
     fleets.command('provision').requiredOption('--request-id <uuid>', 'Stable UUID; reuse with the same name on retry')
         .option('--name <name>', 'Optional fleet name')
         .action(async (opts) => {

package/dist/dials.js

@@ -1,13 +1,16 @@
 import { readFile } from 'node:fs/promises';
 export function registerDials(program, dependencies) {
     const dials = program.command('dials').description('Dials: phone numbers and calls for agents')
-        .requiredOption('--workspace <id>', 'selected workspace')
-        .requiredOption('--project <id>', 'selected project')
-        .requiredOption('--environment <id>', 'selected environment');
+        .option('--workspace <id>', 'workspace (default: an API key\'s bound workspace)')
+        .option('--project <id>', 'project (default: an API key\'s bound project)')
+        .option('--environment <id>', 'environment (default: an API key\'s bound environment)');
     const context = async () => {
         const client = await dependencies.client();
         const options = dials.opts();
-        const scope = { organizationId: await dependencies.orgId(client), workspaceId: options.workspace, projectId: options.project, environmentId: options.environment };
+        // An org API key carries a signed project/workspace/environment binding that Dials fills in; a flag that differs from it is refused.
+        const scope = { organizationId: await dependencies.orgId(client),
+            ...(options.workspace ? { workspaceId: options.workspace } : {}), ...(options.project ? { projectId: options.project } : {}),
+            ...(options.environment ? { environmentId: options.environment } : {}) };
         return { client, scope };
     };
     const emit = (data) => dependencies.emit(data, () => JSON.stringify(data, null, 2));

package/dist/fleets.js

@@ -39,6 +39,34 @@ export function registerFleets(program, client, emit, keyInput = readFoundryKey)
     });
     agents.command('stop <agent_id>').action(async (id) => emit(await (await client()).fleets.agents.stop(id)));
     agents.command('recover <agent_id>').action(async (id) => emit(await (await client()).fleets.agents.recover(id)));
+    agents.command('update <agent_id>').description('Change name, model, instructions or memory (memory needs a stopped agent)')
+        .option('--name <name>').option('--model <model>').option('--clear-model', 'use the Foundry default model')
+        .option('--instructions <text>').option('--clear-instructions', 'remove the instructions')
+        .option('--memory <provider>', 'memory provider (minds, files or custom)').option('--namespace <namespace>').option('--endpoint <url>')
+        .action(async (id, options) => {
+        if (options.model !== undefined && options.clearModel)
+            throw new Error('Use --model or --clear-model, not both.');
+        if (options.instructions !== undefined && options.clearInstructions)
+            throw new Error('Use --instructions or --clear-instructions, not both.');
+        if ((options.namespace !== undefined || options.endpoint !== undefined) && options.memory === undefined)
+            throw new Error('--namespace and --endpoint need --memory.');
+        if (options.memory !== undefined && !['minds', 'files', 'custom'].includes(options.memory))
+            throw new Error('Memory provider must be minds, files, or custom.');
+        if (options.memory === 'custom' && !options.endpoint)
+            throw new Error('Custom memory requires --endpoint.');
+        const body = {
+            ...(options.name !== undefined ? { name: options.name } : {}),
+            ...(options.clearModel ? { model: null } : options.model !== undefined ? { model: options.model } : {}),
+            ...(options.clearInstructions ? { instructions: null } : options.instructions !== undefined ? { instructions: options.instructions } : {}),
+            ...(options.memory !== undefined ? { memory: { provider: options.memory, ...(options.namespace ? { namespace: options.namespace } : {}), ...(options.endpoint ? { endpoint: options.endpoint } : {}) } } : {}),
+        };
+        if (!Object.keys(body).length)
+            throw new Error('Provide at least one of --name, --model, --clear-model, --instructions, --clear-instructions or --memory.');
+        emit(await (await client()).fleets.agents.update(id, body));
+    });
+    agents.command('delete <agent_id>').description('Delete a stopped agent and its log').action(async (id) => emit(await (await client()).fleets.agents.delete(id)));
+    agents.command('logs <agent_id>').description('Read the agent operation log, oldest first').option('--after <seq>', 'next_after from the previous page').option('--limit <n>', '1–200 entries')
+        .action(async (id, options) => emit(await (await client()).fleets.agents.logs(id, { ...(options.after !== undefined ? { after: Number(options.after) } : {}), ...(options.limit !== undefined ? { limit: Number(options.limit) } : {}) })));
     const instances = fleets.command('instances').description('Actual admitted Henry Host status');
     instances.command('list').option('--limit <number>').option('--after <instance_id>').action(async (options) => {
         emit(await (await client()).fleets.instances.list({ ...(options.limit ? { limit: Number(options.limit) } : {}), ...(options.after ? { after: options.after } : {}) }));
@@ -69,4 +97,6 @@ export function registerFleets(program, client, emit, keyInput = readFoundryKey)
     tasks.command('get <task_id>').action(async (id) => emit(await (await client()).fleets.tasks.get(id)));
     tasks.command('cancel <task_id>').action(async (id) => emit(await (await client()).fleets.tasks.cancel(id)));
     tasks.command('receipt <task_id>').action(async (id) => emit(await (await client()).fleets.tasks.receipt(id)));
+    tasks.command('logs <task_id>').description('Read the task lifecycle and output log').option('--after <seq>', 'next_after from the previous read')
+        .action(async (id, options) => emit(await (await client()).fleets.tasks.logs(id, options.after !== undefined ? { after: Number(options.after) } : {})));
 }

package/dist/flocks.d.ts

@@ -1,3 +1,9 @@
 import type { Command } from 'commander';
 import type { Genesis } from '@onesi/genesis';
-export declare function registerFlocks(program: Command, client: () => Promise<Genesis>, emit: (data: unknown, pretty: () => string) => void, env?: Record<string, string | undefined>): void;
+export declare function scrub(value: unknown): unknown;
+/** A reference to a key the org already holds in Blinds or Secret Manager (never the key itself). */
+export declare function checkSecretRef(ref: string): string;
+/** One line from stdin. On a terminal the keystrokes are read raw and never echoed; piped input is read to its end. */
+export declare function readPastedCode(): Promise<string>;
+export declare function checkCode(raw: string): string;
+export declare function registerFlocks(program: Command, client: () => Promise<Genesis>, emit: (data: unknown, pretty: () => string) => void, env?: Record<string, string | undefined>, readCode?: () => Promise<string>, isJson?: () => boolean): void;

package/dist/flocks.js

@@ -1,5 +1,82 @@
+import { Option } from 'commander';
 import { readFunctionJson } from './function-input.js';
-export function registerFlocks(program, client, emit, env = process.env) {
+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];
@@ -7,10 +84,12 @@ export function registerFlocks(program, client, emit, env = process.env) {
             throw new Error(`Set ${name} in the environment; do not pass Flocks credentials as command-line arguments.`);
         return value;
     };
-    const show = async (run) => {
+    const show = async (run, pretty) => {
         const data = await run(await client());
-        emit(data, () => JSON.stringify(data, null, 2));
+        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');
@@ -34,6 +113,7 @@ export function registerFlocks(program, client, emit, env = process.env) {
     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))));
@@ -69,4 +149,178 @@ export function registerFlocks(program, client, emit, env = process.env) {
             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/henry.d.ts

@@ -1,3 +1,7 @@
 import type { Command } from 'commander';
 import type { Genesis } from '@onesi/genesis';
-export declare function addHenryCommands(program: Command, client: () => Promise<Genesis>, output: (value: unknown) => void): void;
+/** `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

@@ -1,5 +1,15 @@
 import { readFoundryKey } from './fleets.js';
-export function addHenryCommands(program, client, output) {
+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')
@@ -12,6 +22,55 @@ export function addHenryCommands(program, client, output) {
     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))

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;