@onesi/genesis-cli 0.0.1-stage → 0.1.13

package/dist/dials.js

@@ -0,0 +1,96 @@
+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');
+    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 };
+        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,72 @@
+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)));
+    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)));
+}

package/dist/flocks.d.ts

@@ -0,0 +1,3 @@
+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;

package/dist/flocks.js

@@ -0,0 +1,72 @@
+import { readFunctionJson } from './function-input.js';
+export function registerFlocks(program, client, emit, env = process.env) {
+    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) => {
+        const data = await run(await client());
+        emit(data, () => JSON.stringify(data, null, 2));
+    };
+    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)));
+    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') }));
+    });
+}

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,3 @@
+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;

package/dist/henry.js

@@ -0,0 +1,26 @@
+import { readFoundryKey } from './fleets.js';
+export function addHenryCommands(program, client, output) {
+    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('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-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 {};

package/dist/hives-marketplace.js

@@ -0,0 +1,29 @@
+import { Option } from 'commander';
+import { readFunctionJson } from './function-input.js';
+function number(value) { if (value === undefined)
+    return undefined; if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)))
+    throw new Error('Invalid page option.'); return Number(value); }
+/** Environment values belong in a bounded private JSON file, never command-line options. */
+export function registerHivesMarketplace(hives, deps) {
+    const m = hives.command('marketplace').description('Existing Hives packages, publication and persisted installations');
+    const output = (data) => deps.emit(data, () => JSON.stringify(data, null, 2));
+    const read = deps.readRequest ?? readFunctionJson;
+    const api = async () => (await deps.client()).hives.marketplace;
+    m.command('list <project_id>').option('--query <value>').option('--category <value>').option('--free-only').option('--verified-only')
+        .addOption(new Option('--sort <field>').choices(['name', 'installs', 'stars', 'created', 'updated']))
+        .addOption(new Option('--order <direction>').choices(['asc', 'desc'])).option('--page <number>').option('--page-size <number>')
+        .action(async (project, o) => output(await (await api()).list(project, { q: o.query, category: o.category, free_only: o.freeOnly, verified_only: o.verifiedOnly, sort: o.sort, order: o.order, page: number(o.page), page_size: number(o.pageSize) })));
+    m.command('get <project_id> <slug>').option('--version <semver>').action(async (project, slug, o) => output(await (await api()).get(project, slug, { version: o.version })));
+    m.command('versions <project_id> <slug>').option('--page <number>').option('--page-size <number>').action(async (project, slug, o) => output(await (await api()).versions(project, slug, { page: number(o.page), page_size: number(o.pageSize) })));
+    for (const action of ['categories', 'featured'])
+        m.command(`${action} <project_id>`).action(async (project) => output(await (await api())[action](project)));
+    m.command('publish <project_id>').requiredOption('--request-file <path>', 'JSON publication with an owned uploaded module_hash and immutable version')
+        .action(async (project, o) => output(await (await api()).publish(project, await read(o.requestFile, 512 * 1024))));
+    for (const action of ['install', 'update'])
+        m.command(`${action} <project_id> <slug>`).requiredOption('--request-file <path>', 'JSON version and env_overrides; use {} for defaults')
+            .action(async (project, slug, o) => output(await (await api())[action](project, slug, await read(o.requestFile, 512 * 1024))));
+    m.command('installed <project_id>').option('--page <number>').option('--page-size <number>').action(async (project, o) => output(await (await api()).installed(project, { page: number(o.page), page_size: number(o.pageSize) })));
+    m.command('installation <project_id> <installation_id>').action(async (project, id) => output(await (await api()).getInstallation(project, id)));
+    for (const action of ['reconcile', 'uninstall'])
+        m.command(`${action} <project_id> <installation_id>`).action(async (project, id) => output(await (await api())[action](project, id)));
+}

package/dist/hives-node-transport.d.ts

@@ -0,0 +1,6 @@
+import { type GenesisOptions } from '@onesi/genesis';
+export declare function closeHivesNodeTransport(): Promise<void>;
+export declare function hivesOperationBudget(id: string): number;
+/** Hives leaf transport. Caller fetch overrides stay authoritative; only native
+ * global fetch gets our Agent. Every operation retains an overall body deadline. */
+export declare function createHivesNodeTransport(opts: GenesisOptions, callerSignal?: AbortSignal): typeof fetch;

package/dist/hives-node-transport.js

@@ -0,0 +1,147 @@
+import { Agent } from 'undici';
+import { Genesis, operationTable } from '@onesi/genesis';
+// Node's native fetch accepts a compatible per-request dispatcher. Never change
+// the global dispatcher or the portable SDK: other products retain their transport.
+const agentOptions = { headersTimeout: 340_000, bodyTimeout: 340_000, connect: { timeout: 5_000 }, connections: 4, pipelining: 1 };
+let agent;
+const nativeAgent = () => agent ??= new Agent(agentOptions);
+export async function closeHivesNodeTransport() {
+    const current = agent;
+    agent = undefined;
+    await current?.destroy();
+}
+export function hivesOperationBudget(id) {
+    if (['hives_list_buckets', 'hives_create_bucket', 'hives_get_bucket', 'hives_delete_bucket', 'hives_list_objects', 'hives_upload_object', 'hives_upload_object_by_key', 'hives_delete_object', 'hives_delete_object_by_key', 'hives_download_object_by_key', 'hives_get_cors_config', 'hives_set_cors_config', 'hives_generate_presigned_url', 'hives_reconcile'].includes(id))
+        return 100_000;
+    if (id === 'hives_cancel_deployment' || id === 'hives_delete_deployment' || id === 'hives_stop_deployment')
+        return 330_000;
+    if (['hives_create_deployment', 'hives_upload_deployment', 'hives_invoke_deployment', 'hives_invoke_function', 'hives_invoke_function_async'].includes(id))
+        return 40_000;
+    if (['hives_create_function', 'hives_update_function', 'hives_delete_function'].includes(id))
+        return 100_000;
+    return 20_000;
+}
+const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const templatePattern = (value) => new RegExp('^' + value.split(/(\{[^}]+\})/).map((part) => part.startsWith('{') ? '[^/]+' : escape(part)).join('') + '$');
+/** Hives leaf transport. Caller fetch overrides stay authoritative; only native
+ * global fetch gets our Agent. Every operation retains an overall body deadline. */
+export function createHivesNodeTransport(opts, callerSignal) {
+    const supplied = opts.fetch ?? globalThis.fetch;
+    const underlying = supplied.bind(globalThis);
+    const useNative = supplied === globalThis.fetch;
+    const resolver = new Genesis(opts);
+    const routes = Object.entries(operationTable)
+        .filter(([, op]) => op.service === 'hives' && !op.internal)
+        .flatMap(([id, op]) => {
+        const direct = resolver.routing === 'direct';
+        let base;
+        try {
+            base = new URL(direct ? (opts.upstreams?.hives ?? op.upstream.base) : resolver.baseUrl);
+        }
+        catch {
+            throw new Error('Invalid Hives service address.');
+        }
+        const path = direct ? op.upstream.path : op.path;
+        const prefix = base.pathname.replace(/\/+$/, '');
+        const paths = [path];
+        if (!direct && path.startsWith('/v1/hives/'))
+            paths.push(path.replace('/v1/hives/', '/hives/v1/'));
+        return paths.map((p) => ({ id, origin: base.origin, method: direct ? op.upstream.method : op.method, pattern: templatePattern(prefix + p) }));
+    });
+    return (async (input, init = {}) => {
+        let url;
+        try {
+            url = new URL(input instanceof Request ? input.url : String(input));
+        }
+        catch {
+            throw new Error('Invalid Hives request address.');
+        }
+        const method = (init.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+        const route = routes.find((entry) => entry.origin === url.origin && entry.method === method && entry.pattern.test(url.pathname));
+        if (!route)
+            return underlying(input, init);
+        const controller = new AbortController();
+        let message = 'Hives transport failed. Refresh the resource and retry.';
+        const safeError = () => new Error(message);
+        const signals = [...new Set([callerSignal, init.signal, input instanceof Request ? input.signal : undefined].filter((signal) => !!signal))];
+        const canceled = () => {
+            message = 'Hives request canceled before completion. Refresh the resource before retrying.';
+            controller.abort();
+        };
+        for (const signal of signals)
+            signal.addEventListener('abort', canceled, { once: true });
+        const timer = setTimeout(() => {
+            message = 'Hives request deadline exceeded. Refresh the resource before retrying.';
+            controller.abort();
+        }, hivesOperationBudget(route.id));
+        timer.unref();
+        let abortReject = () => { };
+        let reader;
+        let bodyController;
+        const aborted = () => {
+            abortReject(safeError());
+            bodyController?.error(safeError());
+            void reader?.cancel().catch(() => { });
+            cleanup();
+        };
+        controller.signal.addEventListener('abort', aborted, { once: true });
+        const abortPromise = new Promise((_, reject) => { abortReject = reject; });
+        void abortPromise.catch(() => { });
+        const cleanup = () => {
+            clearTimeout(timer);
+            for (const signal of signals)
+                signal.removeEventListener('abort', canceled);
+            controller.signal.removeEventListener('abort', aborted);
+        };
+        if (signals.some((signal) => signal.aborted))
+            canceled();
+        try {
+            if (controller.signal.aborted)
+                throw safeError();
+            const requestInit = {
+                ...init, signal: controller.signal, cache: 'no-store',
+                redirect: init.redirect === 'manual' ? 'manual' : 'error',
+                ...(useNative ? { dispatcher: nativeAgent() } : {}),
+            };
+            const pending = underlying(input, requestInit);
+            // A caller transport may ignore AbortSignal. Reject on our budget anyway,
+            // and discard any late response rather than presenting an acknowledgement.
+            void pending.then((response) => { if (controller.signal.aborted)
+                void response.body?.cancel().catch(() => { }); }, () => { });
+            const response = await Promise.race([pending, abortPromise]);
+            if (controller.signal.aborted)
+                throw safeError();
+            if (!response.body) {
+                cleanup();
+                return response;
+            }
+            reader = response.body.getReader();
+            const body = new ReadableStream({
+                start(value) { bodyController = value; },
+                async pull(value) {
+                    try {
+                        const next = await reader.read();
+                        if (controller.signal.aborted)
+                            return;
+                        if (next.done) {
+                            cleanup();
+                            value.close();
+                        }
+                        else
+                            value.enqueue(next.value);
+                    }
+                    catch {
+                        cleanup();
+                        value.error(safeError());
+                    }
+                },
+                async cancel() { cleanup(); await reader.cancel().catch(() => { }); },
+            });
+            return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+        }
+        catch {
+            cleanup();
+            throw safeError();
+        }
+    });
+}

package/dist/hives-operations.d.ts

@@ -0,0 +1,9 @@
+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>>;
+};
+export declare function registerHivesOperations(hives: Command, deps: Deps): void;
+export {};

package/dist/hives-operations.js

@@ -0,0 +1,61 @@
+import { registerHivesResources } from './hives-resources.js';
+import { Option } from 'commander';
+import { readFunctionJson } from './function-input.js';
+function metricsOptions(command) {
+    return command.option('--start <time>', 'inclusive UTC timestamp').option('--end <time>', 'exclusive UTC timestamp')
+        .addOption(new Option('--resolution <value>', 'time bucket').choices(['minute', 'fiveminutes', 'fifteenminutes', 'hour', 'day']))
+        .addOption(new Option('--aggregation <value>', 'supported aggregation').choices(['sum', 'avg', 'min', 'max', 'count', 'p50', 'p90', 'p95', 'p99']));
+}
+const integer = (value, name, max) => {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < 1 || Number(value) > max) {
+        throw new Error(`${name} must be an integer from 1 to ${max}.`);
+    }
+    return Number(value);
+};
+const paging = (command) => command.option('--page <number>').option('--per-page <number>');
+const pagination = (o) => ({ page: integer(o.page, '--page', 10000), per_page: integer(o.perPage, '--per-page', 100) });
+export function registerHivesOperations(hives, deps) {
+    registerHivesResources(hives, deps);
+    const output = (data) => deps.emit(data, () => JSON.stringify(data, null, 2));
+    const read = deps.readRequest ?? readFunctionJson;
+    const settings = hives.command('settings').description('Stored project preferences and actual engine capabilities');
+    settings.command('get <project_id>').action(async (project) => output(await (await deps.client()).hives.settings.get(project)));
+    settings.command('update <project_id>').requiredOption('--request-file <path>', 'JSON settings patch')
+        .action(async (project, o) => output(await (await deps.client()).hives.settings.update(project, await read(o.requestFile, 64 * 1024))));
+    const crons = hives.command('crons').description('Waggle schedules and persisted run outcomes');
+    paging(crons.command('list <project_id>')).action(async (project, o) => output(await (await deps.client()).hives.crons.list(project, pagination(o))));
+    crons.command('get <project_id> <cron_id>').action(async (project, cron) => output(await (await deps.client()).hives.crons.get(project, cron)));
+    crons.command('create <project_id>').requiredOption('--request-file <path>', 'JSON name, schedule, handler, timezone and enabled preference')
+        .action(async (project, o) => {
+        const body = await read(o.requestFile, 64 * 1024);
+        if (typeof body.name !== 'string' || typeof body.schedule !== 'string' || typeof body.handler !== 'string')
+            throw new Error('Cron JSON requires name, schedule and handler strings.');
+        output(await (await deps.client()).hives.crons.create(project, { ...body, name: body.name, schedule: body.schedule, handler: body.handler }));
+    });
+    crons.command('update <project_id> <cron_id>').requiredOption('--request-file <path>', 'JSON schedule patch')
+        .action(async (project, cron, o) => output(await (await deps.client()).hives.crons.update(project, cron, await read(o.requestFile, 64 * 1024))));
+    for (const action of ['delete', 'pause', 'resume', 'trigger']) {
+        crons.command(`${action} <project_id> <cron_id>`)
+            .description(action === 'trigger' ? 'Admit one run; inspect runs for completion. Does not retry.' : `${action} an owned schedule`)
+            .action(async (project, cron) => output(await (await deps.client()).hives.crons[action](project, cron)));
+    }
+    paging(crons.command('runs <project_id> <cron_id>')).addOption(new Option('--status <state>', 'persisted run status').choices(['pending', 'running', 'success', 'failed', 'timeout', 'cancelled']))
+        .option('--since <time>').option('--until <time>')
+        .action(async (project, cron, o) => output(await (await deps.client()).hives.crons.runs(project, cron, { ...pagination(o), status: o.status, since: o.since, until: o.until })));
+    const metrics = hives.command('metrics').description('Retained completed API observations; unavailable measurements remain null');
+    for (const kind of ['project', 'requests', 'latency', 'errors', 'resources']) {
+        metricsOptions(metrics.command(`${kind} <project_id>`))
+            .action(async (project, q) => output(await (await deps.client()).hives.metrics[kind](project, q)));
+    }
+    metrics.command('dashboard <project_id>').addOption(new Option('--period <value>').choices(['1h', '24h', '7d', '30d']))
+        .action(async (project, q) => output(await (await deps.client()).hives.metrics.dashboard(project, q)));
+    for (const kind of ['function', 'invocations']) {
+        metricsOptions(metrics.command(`${kind} <project_id> <function_id>`))
+            .action(async (project, id, q) => output(await (await deps.client()).hives.metrics[kind](project, id, q)));
+    }
+    metricsOptions(metrics.command('deployment <project_id> <deployment_id>'))
+        .action(async (project, id, q) => output(await (await deps.client()).hives.metrics.deployment(project, id, q)));
+    metrics.command('realtime <project_id>').action(async (project) => output(await (await deps.client()).hives.metrics.realtime(project)));
+}