@onesi/genesis-cli 0.0.1-stage → 0.2.0

package/dist/device-login.js

@@ -0,0 +1,173 @@
+import { LIFEID_ISSUER } from './lifeid-native.js';
+import { errorToken } from '@onesi/genesis';
+/** RFC 8628 device grant against One account, for agents and machines without a local browser. */
+export const DEVICE_CLIENT_ID = 'genesis-cli-device';
+export const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+const DEVICE_SCOPE = 'openid offline_access email profile';
+const MAX_BODY = 32_768;
+class DeviceLoginError extends Error {
+}
+function object(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v) ? v : undefined;
+}
+function secret(v) {
+    return typeof v === 'string' && v.length > 0 && v.length <= 16_384 && !/[\s\x00-\x1f\x7f]/.test(v);
+}
+function claimsOf(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3 || !parts.every(p => /^[A-Za-z0-9_-]+$/.test(p)))
+            return undefined;
+        return object(JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8')));
+    }
+    catch {
+        return undefined;
+    }
+}
+const ISSUER_HOST = new URL(LIFEID_ISSUER).host;
+/** https on exactly the issuer's host (and port), with no userinfo or control characters. */
+function onIssuer(u) {
+    if (typeof u !== 'string' || u.length > 2048 || /[\s\x00-\x1f\x7f-\x9f]/.test(u))
+        return false;
+    try {
+        const url = new URL(u);
+        return url.protocol === 'https:' && url.host === ISSUER_HOST && url.username === '' && url.password === '' && !/@/.test(u.split(/[/?#]/, 3)[2] ?? '');
+    }
+    catch {
+        return false;
+    }
+}
+function invalid() { throw new DeviceLoginError('One account returned an invalid device login response. Run `genesis login --device` again.'); }
+/** Form POST to One account: bounded body, no redirects, 15s deadline, and no response echo. */
+async function postForm(c, path, form, signal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    const timer = setTimeout(abort, 15_000);
+    signal?.addEventListener('abort', abort, { once: true });
+    try {
+        const response = await c.fetch(`${LIFEID_ISSUER}${path}`, {
+            method: 'POST', redirect: 'error', cache: 'no-store', signal: controller.signal,
+            headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+            body: new URLSearchParams(form).toString(),
+        });
+        if (!/^application\/json(?:;|$)/i.test(response.headers.get('content-type') ?? '')) {
+            void response.body?.cancel().catch(() => { });
+            throw new DeviceLoginError(`One account request failed (${response.status}).`);
+        }
+        const reader = response.body?.getReader();
+        if (!reader)
+            invalid();
+        const chunks = [];
+        let size = 0;
+        for (;;) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            size += part.value.byteLength;
+            if (size > MAX_BODY) {
+                void reader.cancel().catch(() => { });
+                invalid();
+            }
+            chunks.push(part.value);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        }
+        catch {
+            invalid();
+        }
+        return { status: response.status, body: object(parsed) ?? invalid() };
+    }
+    catch (error) {
+        if (error instanceof DeviceLoginError)
+            throw error;
+        if (signal?.aborted)
+            throw new DeviceLoginError('One account device login cancelled.');
+        throw new DeviceLoginError('One account transport failed. No automatic retry was made.');
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', abort);
+    }
+}
+export async function startDeviceLogin(c, signal) {
+    const { status, body } = await postForm(c, '/v4/oauth/device_authorization', { client_id: DEVICE_CLIENT_ID, scope: DEVICE_SCOPE }, signal);
+    if (status !== 200)
+        throw new DeviceLoginError(`One account refused the device login (${status}).`);
+    const { device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval } = body;
+    if (!secret(device_code) || typeof user_code !== 'string' || !/^[BCDFGHJKLMNPQRSTVWXZ]{4}-[BCDFGHJKLMNPQRSTVWXZ]{4}$/.test(user_code)
+        || typeof expires_in !== 'number' || !Number.isInteger(expires_in) || expires_in < 1 || expires_in > 3600
+        || typeof interval !== 'number' || !Number.isInteger(interval) || interval < 1 || interval > 60)
+        invalid();
+    if (!onIssuer(verification_uri) || !onIssuer(verification_uri_complete)) {
+        throw new DeviceLoginError(`One account returned a verification URL outside ${ISSUER_HOST}. Refusing to show it; run \`genesis login --device\` again.`);
+    }
+    return { deviceCode: device_code, userCode: user_code, verificationUri: verification_uri,
+        verificationUriComplete: verification_uri_complete, expiresIn: expires_in, interval };
+}
+/** Saved session from an OAuth token response. Authority stays with the One account verifier. */
+export function parseDeviceTokens(body, now = Date.now() / 1000) {
+    const access = body.access_token, refresh = body.refresh_token;
+    if (body.token_type !== 'Bearer' || !secret(access) || !secret(refresh))
+        invalid();
+    const claims = claimsOf(access);
+    const exp = claims?.exp;
+    if (!claims || claims.iss !== LIFEID_ISSUER || claims.kind !== 'human' || typeof claims.sub !== 'string'
+        || typeof claims.sid !== 'string' || typeof exp !== 'number' || exp <= now
+        || claims.cnf !== undefined || claims.cap !== undefined || claims.obo !== undefined)
+        invalid();
+    const org = typeof claims.org === 'string' ? claims.org : undefined;
+    const email = typeof claims.email === 'string' ? claims.email : undefined;
+    return { access_token: access, refresh_token: refresh, user: { id: claims.sub, ...(email ? { email } : {}) },
+        ...(org ? { organization_id: org } : {}), expires_at: exp, client_id: DEVICE_CLIENT_ID,
+        auth: { kind: 'lifeid-device', issuer: LIFEID_ISSUER, client_id: DEVICE_CLIENT_ID, principal_id: claims.sub, session_id: claims.sid } };
+}
+/** Poll until approved, denied or expired, honouring `interval` and `slow_down`. */
+export async function completeDeviceLogin(c, start, signal) {
+    const sleep = c.sleep ?? ((ms) => new Promise(r => setTimeout(r, ms)));
+    const deadline = Date.now() + start.expiresIn * 1000;
+    let interval = start.interval;
+    for (;;) {
+        await sleep(interval * 1000);
+        if (signal?.aborted)
+            throw new DeviceLoginError('One account device login cancelled.');
+        if (Date.now() > deadline)
+            throw new DeviceLoginError('The device code expired. Run `genesis login --device` again.');
+        const { status, body } = await postForm(c, '/v4/oauth/token', { grant_type: DEVICE_GRANT, client_id: DEVICE_CLIENT_ID, device_code: start.deviceCode }, signal);
+        if (status === 200)
+            return parseDeviceTokens(body);
+        // RFC 8628 string errors from Auth; the envelope form (error.code) is accepted too.
+        switch (errorToken(body)) {
+            case 'authorization_pending': continue;
+            case 'slow_down':
+                interval = Math.min(interval + 5, 60);
+                continue;
+            case 'access_denied': throw new DeviceLoginError('Sign-in was denied on the verification page.');
+            case 'expired_token': throw new DeviceLoginError('The device code expired. Run `genesis login --device` again.');
+            default: throw new DeviceLoginError(`One account refused the device login (${status}). Run \`genesis login --device\` again.`);
+        }
+    }
+}
+/** Rotate a device session through the OAuth refresh grant of the same public client. */
+export async function refreshDeviceLogin(c, saved) {
+    if (!secret(saved.refresh_token))
+        throw new DeviceLoginError('Session expired. Run `genesis login --device`.');
+    const { status, body } = await postForm(c, '/v4/oauth/token', { grant_type: 'refresh_token', client_id: DEVICE_CLIENT_ID, refresh_token: saved.refresh_token });
+    if (status !== 200)
+        throw new DeviceLoginError(`One account refresh failed (${status}). Run \`genesis login --device\` again.`);
+    const next = parseDeviceTokens(body);
+    if (next.auth?.principal_id !== saved.auth?.principal_id)
+        invalid();
+    return next;
+}
+export function requireDeviceSaved(s) {
+    const a = s.auth;
+    const claims = claimsOf(s.access_token);
+    if (!a || a.kind !== 'lifeid-device' || a.issuer !== LIFEID_ISSUER || a.client_id !== DEVICE_CLIENT_ID || s.client_id !== DEVICE_CLIENT_ID
+        || !claims || claims.iss !== a.issuer || claims.kind !== 'human' || claims.sub !== a.principal_id || claims.sid !== a.session_id
+        || (s.organization_id !== undefined && claims.org !== s.organization_id)
+        || claims.cnf !== undefined || claims.cap !== undefined || claims.obo !== undefined) {
+        throw new Error('Saved One account device session is inconsistent. Run `genesis login --device` again.');
+    }
+}

package/dist/dials.d.ts

@@ -0,0 +1,7 @@
+import { Command } from 'commander';
+import type { Genesis } from '@onesi/genesis';
+export declare function registerDials(program: Command, dependencies: {
+    client: () => Promise<Genesis>;
+    orgId: (client: Genesis) => Promise<string>;
+    emit: (data: unknown, pretty: () => string) => void;
+}): void;

package/dist/dials.js

@@ -0,0 +1,99 @@
+import { readFile } from 'node:fs/promises';
+export function registerDials(program, dependencies) {
+    const dials = program.command('dials').description('Dials: phone numbers and calls for agents')
+        .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();
+        // 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));
+    const numbers = dials.command('numbers').description('Carrier number inventory');
+    numbers.command('list', { isDefault: true }).action(async () => { const { client, scope } = await context(); emit(await client.dials.numbers.list(scope)); });
+    numbers.command('search').option('--area-code <code>', 'three digit area code').option('--filters <json-or-@file>', 'carrier search filters, including capabilities and rate center').action(async (options) => {
+        const { client, scope } = await context();
+        const text = options.filters?.startsWith('@') ? await readFile(options.filters.slice(1), 'utf8') : options.filters;
+        const filters = text ? JSON.parse(text) : {};
+        if (!filters || typeof filters !== 'object' || Array.isArray(filters))
+            throw new Error('Search filters must be a JSON object.');
+        const allowed = new Set(['areaCode', 'exchangeCode', 'localCallingArea', 'contains', 'startsWith', 'endsWith', 'repeatingDigit', 'repeatingDigitCount', 'region', 'locality', 'postalCode', 'rateCenter', 'lata', 'nearNumber', 'nearLatLong', 'distance', 'excludeAddressRequired', 'excludeLocalAddressRequired', 'excludeForeignAddressRequired', 'beta', 'voice', 'sms', 'mms', 'fax', 'numberType', 'limit']);
+        if (Object.keys(filters).some(key => !allowed.has(key)))
+            throw new Error('Unsupported Dials search filter. Scope is selected by the command context.');
+        emit(await client.dials.numbers.search(scope, { ...filters, ...(options.areaCode ? { areaCode: options.areaCode } : {}) }));
+    });
+    numbers.command('reconciliations').action(async () => { const { client, scope } = await context(); emit(await client.dials.numbers.reconciliations(scope)); });
+    numbers.command('drift').action(async () => { const { client, scope } = await context(); emit(await client.dials.numbers.drift(scope)); });
+    dials.command('overview').action(async () => { const { client, scope } = await context(); emit(await client.dials.overview.summary(scope)); });
+    dials.command('operating-surface').action(async () => { const { client, scope } = await context(); emit(await client.dials.overview.operatingSurface(scope)); });
+    for (const [name, list, create] of [['people', 'dials_listHumanProfiles', 'dials_createHumanProfile'], ['agents', 'dials_listAgents', 'dials_createAgent'], ['voice', 'dials_listVoiceProfiles', 'dials_createVoiceProfile']]) {
+        const profiles = dials.command(name).description('Saved profile configuration in the selected scope');
+        profiles.command('list', { isDefault: true }).action(async () => { const { client, scope } = await context(); emit(await client.call(list, scope)); });
+        profiles.command('create').requiredOption('--body <json-or-@file>', 'Unassigned profile fields and actorId; same-name POST updates the stored profile').action(async (options) => {
+            const { client, scope } = await context();
+            const text = options.body.startsWith('@') ? await readFile(options.body.slice(1), 'utf8') : options.body;
+            const body = JSON.parse(text);
+            if (!body || typeof body !== 'object' || Array.isArray(body) || 'phoneNumberId' in body)
+                throw new Error('Supply unassigned profile fields; use numbers assign after saving.');
+            emit(await client.call(create, { body: { ...body, scope } }));
+        });
+    }
+    const readBody = async (value) => {
+        const body = JSON.parse(value.startsWith('@') ? await readFile(value.slice(1), 'utf8') : value);
+        if (!body || typeof body !== 'object' || Array.isArray(body))
+            throw new Error('Dials body must be a JSON object.');
+        return body;
+    };
+    const messages = dials.command('messages').description('Saved messages, templates and pending registration configuration');
+    messages.command('list', { isDefault: true }).action(async () => { const { client, scope } = await context(); emit(await client.dials.messages.list(scope)); });
+    messages.command('send').requiredOption('--body <json-or-@file>', 'Explicit approvals, actor, sender, destination, body and idempotency key')
+        .action(async (options) => { const { client, scope } = await context(); const body = await readBody(options.body); emit(await client.call('dials_createOutboundMessage', { body: { ...body, scope } })); });
+    for (const [name, list, create] of [
+        ['templates', 'dials_listMessageTemplates', 'dials_createMessageTemplate'],
+        ['brands', 'dials_listMessagingBrands', 'dials_createMessagingBrand'],
+        ['campaigns', 'dials_listMessagingCampaigns', 'dials_createMessagingCampaign'],
+    ]) {
+        const group = messages.command(name).description('Scoped saved configuration; creation is not provider approval');
+        group.command('list', { isDefault: true }).action(async () => { const { client, scope } = await context(); emit(await client.call(list, scope)); });
+        group.command('create').requiredOption('--body <json-or-@file>', 'Configuration fields and actorId')
+            .action(async (options) => { const { client, scope } = await context(); const body = await readBody(options.body); emit(await client.call(create, { body: { ...body, scope } })); });
+        if (name === 'campaigns')
+            group.command('assign').requiredOption('--campaign <id>', 'Owned campaign ID').requiredOption('--body <json-or-@file>', 'Owned phoneNumberId and actorId')
+                .action(async (options) => { const { client, scope } = await context(); const body = await readBody(options.body); emit(await client.call('dials_assignCampaignNumber', { campaign_id: options.campaign, body: { ...body, scope } })); });
+    }
+    const routing = dials.command('routing').description('Managed owned-number inbound policies; workflow documents are separate');
+    routing.command('list', { isDefault: true }).action(async () => { const { client, scope } = await context(); emit(await client.dials.routing.list(scope)); });
+    routing.command('create').requiredOption('--body <json-or-@file>', 'Owned source, supported action, priority and persisted original UUID; creates an enabled policy')
+        .action(async (options) => { const { client, scope } = await context(); const body = await readBody(options.body); emit(await client.call('dials_createRoutingRule', { body: { ...body, scope } })); });
+    routing.command('disable').requiredOption('--rule <id>', 'Owned managed policy ID; record is retained')
+        .action(async (options) => { const { client, scope } = await context(); emit(await client.dials.routing.disable(options.rule, { scope })); });
+    const workflows = dials.command('workflows').description('Persisted routing descriptors; execution is verified separately');
+    workflows.command('list', { isDefault: true }).action(async () => { const { client, scope } = await context(); emit(await client.dials.workflows.list(scope)); });
+    workflows.command('deploy').requiredOption('--body <json-or-@file>', 'Workflow graph and actorId')
+        .action(async (options) => { const { client, scope } = await context(); const body = await readBody(options.body); emit(await client.call('dials_deployWorkflow', { body: { ...body, scope } })); });
+    numbers.command('delete').requiredOption('--number <id>', 'Owned number ID to release at the carrier').requiredOption('--actor <id>', 'Actual actorId').option('--reason <text>', 'Release reason').option('--platform <id>', 'Selected data platform; omitted defaults to dials')
+        .action(async (options) => { const { client, scope } = await context(); emit(await client.dials.numbers.delete({ ...scope, ...(options.platform !== undefined ? { platformId: options.platform } : {}), number_id: options.number, actorId: options.actor, ...(options.reason !== undefined ? { reason: options.reason } : {}) })); });
+    const calls = dials.command('calls').description('Call activity and approved outbound calls');
+    calls.command('list', { isDefault: true }).action(async () => { const { client, scope } = await context(); emit(await client.dials.calls.list(scope)); });
+    // @file keeps structured approval and idempotency fields out of shell history.
+    for (const [parent, name, operation] of [
+        [numbers, 'caller-name', 'dials_updateNumberCallerName'], [numbers, 'reconcile', 'dials_reconcileNumberInventory'],
+        [numbers, 'provision', 'dials_provisionNumber'], [numbers, 'assign', 'dials_assignNumber'], [numbers, 'release', 'dials_releaseNumber'], [numbers, 'e911', 'dials_registerEmergencyAddress'],
+        [calls, 'validate', 'dials_validateOutboundCall'], [calls, 'create', 'dials_createOutboundCall'], [calls, 'recover', 'dials_recoverOutboundCall'],
+    ]) {
+        parent.command(name).requiredOption('--body <json-or-@file>', 'JSON input including actorId and required operation fields')
+            .action(async (options) => {
+            const { client, scope } = await context();
+            const text = options.body.startsWith('@') ? await readFile(options.body.slice(1), 'utf8') : options.body;
+            const body = JSON.parse(text);
+            if (!body || typeof body !== 'object' || Array.isArray(body))
+                throw new Error('Dials body must be a JSON object.');
+            emit(await client.call(operation, { body: { ...body, scope } }));
+        });
+    }
+}

package/dist/fleets.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+import type { Genesis } from '@onesi/genesis';
+export declare function readFoundryKey(input?: AsyncIterable<Uint8Array>): Promise<string>;
+export declare function registerFleets(program: Command, client: () => Promise<Genesis>, emit: (data: unknown) => void, keyInput?: () => Promise<string>): void;

package/dist/fleets.js

@@ -0,0 +1,102 @@
+export async function readFoundryKey(input = process.stdin) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of input) {
+        const bytes = Buffer.from(chunk);
+        size += bytes.length;
+        if (size > 4098)
+            throw new Error('Foundry key must contain at most 4096 bytes.');
+        chunks.push(bytes);
+    }
+    let key;
+    try {
+        key = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks)).replace(/\r?\n$/, '');
+    }
+    catch {
+        throw new Error('Invalid UTF-8 Foundry key on stdin.');
+    }
+    if (!key || Buffer.byteLength(key) > 4096 || /[\r\n\0]/.test(key))
+        throw new Error('Invalid Foundry key on stdin.');
+    return key;
+}
+export function registerFleets(program, client, emit, keyInput = readFoundryKey) {
+    const fleets = program.command('fleets').description('Fleets: managed Henry instances and tasks');
+    const agents = fleets.command('agents').description('Persistent Henry agents on Fleets-managed compute');
+    agents.command('list').action(async () => emit(await (await client()).fleets.agents.list()));
+    agents.command('launch <name>').option('--memory <provider>', 'memory provider (minds, files or custom)', 'minds').option('--namespace <namespace>').option('--endpoint <url>').option('--model <model>').option('--instructions <text>').requiredOption('--idempotency-key <key>', 'stable key to reuse on retry').action(async (name, options) => {
+        const provider = options.memory;
+        if (!['minds', 'files', 'custom'].includes(provider))
+            throw new Error('Memory provider must be minds, files, or custom.');
+        if (provider === 'custom' && !options.endpoint)
+            throw new Error('Custom memory requires --endpoint.');
+        emit(await (await client()).fleets.agents.launch({ name, memory: { provider, ...(options.namespace ? { namespace: options.namespace } : {}), ...(options.endpoint ? { endpoint: options.endpoint } : {}) }, ...(options.model ? { model: options.model } : {}), ...(options.instructions ? { instructions: options.instructions } : {}), idempotency_key: options.idempotencyKey }));
+    });
+    agents.command('get <agent_id>').action(async (id) => emit(await (await client()).fleets.agents.get(id)));
+    agents.command('command <agent_id> <input>').option('--delivery <mode>', 'queue, steer or interrupt', 'queue').action(async (id, input, options) => {
+        if (!['queue', 'steer', 'interrupt'].includes(options.delivery))
+            throw new Error('Delivery must be queue, steer, or interrupt.');
+        emit(await (await client()).fleets.agents.command(id, { input, delivery: options.delivery }));
+    });
+    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 } : {}) }));
+    });
+    instances.command('get <instance_id>').action(async (id) => emit(await (await client()).fleets.instances.get(id)));
+    instances.command('stop <instance_id>').description('Stop admitted Henry compute and retain its data').option('--idempotency-key <uuid>', 'canonical UUID4 to retain after an uncertain reply').action(async (id, options) => emit(await (await client()).fleets.instances.stop(id, { idempotencyKey: options.idempotencyKey })));
+    instances.command('start <instance_id>').description('Connect already admitted Henry compute').option('--idempotency-key <uuid>', 'canonical UUID4 to retain after an uncertain reply').action(async (id, options) => emit(await (await client()).fleets.instances.start(id, { idempotencyKey: options.idempotencyKey })));
+    const connection = fleets.command('connection').description('Organization-owned Foundry connection');
+    connection.command('get').action(async () => emit(await (await client()).fleets.connection.get()));
+    connection.command('set').description('Read a Foundry key from stdin and encrypt it with Genesis KMS').action(async () => {
+        const apiKey = await keyInput();
+        emit(await (await client()).fleets.connection.set(apiKey));
+    });
+    connection.command('delete').action(async () => emit(await (await client()).fleets.connection.delete()));
+    const usage = fleets.command('usage').description('Usage observations derived from your tasks');
+    usage.command('events').description('List task lifecycle and execution-time usage events').option('--limit <n>').option('--before <task_id>')
+        .action(async (options) => emit(await (await client()).fleets.usage.events({ ...(options.limit ? { limit: Number(options.limit) } : {}), ...(options.before ? { before: options.before } : {}) })));
+    const tasks = fleets.command('tasks');
+    tasks.command('list').option('--limit <number>').option('--before <task_id>').action(async (options) => {
+        emit(await (await client()).fleets.tasks.list({ ...(options.limit ? { limit: Number(options.limit) } : {}), ...(options.before ? { before: options.before } : {}) }));
+    });
+    tasks.command('submit <input>').option('--timeout <seconds>', 'task deadline in seconds', '300').requiredOption('--idempotency-key <key>', 'stable key to reuse on retry').action(async (input, options) => {
+        const timeout = Number(options.timeout);
+        if (!Number.isInteger(timeout) || timeout < 1 || timeout > 3600)
+            throw new Error('Timeout must be 1–3600 seconds.');
+        emit(await (await client()).fleets.tasks.submit({ input, timeout_seconds: timeout, idempotency_key: options.idempotencyKey }));
+    });
+    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

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+import type { Genesis } from '@onesi/genesis';
+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;