@onesi/genesis-cli 0.0.0-stage → 0.1.13

package/dist/lifeid-native.d.ts

@@ -0,0 +1,24 @@
+export declare const LIFEID_ISSUER = "https://auth.life.one";
+export declare const GENESIS_CLI_PRODUCT = "genesis-cli";
+export declare const CALLBACK_PATH = "/lifeid/callback";
+/** Exact Auth-owned admission metadata; supplying it does not register a client. */
+export interface NativeRegistration {
+    productId: string;
+    redirectUri: string;
+    audience: string;
+}
+export interface NativeAttempt {
+    readonly browserUrl: string;
+    readonly codeVerifier: string;
+    readonly registration: NativeRegistration;
+    readonly code: Promise<string>;
+    readonly signal: AbortSignal;
+    close(): void;
+}
+export declare function validateRegistration(r: NativeRegistration): number;
+/** Bind the sole registered port before the caller opens or prints the browser URL. */
+export declare function startNativeAttempt(registration: NativeRegistration, options?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    organizationHint?: string;
+}): Promise<NativeAttempt>;

package/dist/lifeid-native.js

@@ -0,0 +1,113 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+export const LIFEID_ISSUER = 'https://auth.life.one';
+export const GENESIS_CLI_PRODUCT = 'genesis-cli';
+export const CALLBACK_PATH = '/lifeid/callback';
+export function validateRegistration(r) {
+    const m = /^http:\/\/127\.0\.0\.1:([1-9][0-9]{3,4})\/lifeid\/callback$/.exec(r.redirectUri);
+    const port = m ? Number(m[1]) : 0;
+    if (r.productId !== GENESIS_CLI_PRODUCT || !m || port < 1024 || port > 65535
+        || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(r.audience)) {
+        throw new Error('One account native login requires the exact admitted Genesis product, loopback callback and audience.');
+    }
+    return port;
+}
+/** Bind the sole registered port before the caller opens or prints the browser URL. */
+export async function startNativeAttempt(registration, options = {}) {
+    registration = { ...registration };
+    const port = validateRegistration(registration);
+    const timeout = options.timeoutMs ?? 300_000;
+    if (!Number.isInteger(timeout) || timeout < 1 || timeout > 300_000)
+        throw new Error('Invalid login deadline.');
+    if (options.signal?.aborted)
+        throw new Error('One account login cancelled.');
+    if (options.organizationHint && !/^o_[0-9A-HJKMNP-TV-Z]{26}$/.test(options.organizationHint)) {
+        throw new Error('Invalid One account organization hint.');
+    }
+    const verifier = randomBytes(48).toString('base64url');
+    const controller = new AbortController();
+    let settled = false;
+    let resolveCode;
+    let rejectCode;
+    const code = new Promise((resolve, reject) => { resolveCode = resolve; rejectCode = reject; });
+    // Binding/open-browser errors may happen before the caller awaits the code.
+    void code.catch(() => { });
+    const server = createServer({ maxHeaderSize: 4096 }, (req, res) => {
+        const reject = (status) => {
+            res.writeHead(status, { 'content-type': 'text/plain', 'cache-control': 'no-store', connection: 'close' });
+            res.end('Invalid One account callback.');
+        };
+        // A malformed request cannot consume a pending code. No body is read/logged.
+        if (settled || req.method !== 'GET' || req.headers.host !== `127.0.0.1:${port}`
+            || req.headers.origin !== undefined || req.headers['transfer-encoding'] !== undefined
+            || (req.headers['content-length'] !== undefined && req.headers['content-length'] !== '0')) {
+            reject(400);
+            return;
+        }
+        const m = /^\/lifeid\/callback\?life_code=([A-Za-z0-9_-]{43})$/.exec(req.url ?? '');
+        if (!m) {
+            reject(400);
+            return;
+        }
+        settled = true;
+        res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store',
+            'referrer-policy': 'no-referrer', 'content-security-policy': "default-src 'none'", connection: 'close' });
+        res.end('One account callback received. Return to Genesis CLI.');
+        server.close();
+        resolveCode(m[1]);
+    });
+    server.requestTimeout = 5000;
+    server.headersTimeout = 5000;
+    server.keepAliveTimeout = 1;
+    server.maxConnections = 4;
+    const close = () => {
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', onAbort);
+        server.close();
+        server.closeAllConnections();
+        if (!settled) {
+            settled = true;
+            rejectCode(new Error('One account login cancelled.'));
+        }
+        controller.abort();
+    };
+    const onAbort = () => close();
+    const timer = setTimeout(() => {
+        if (!settled) {
+            settled = true;
+            rejectCode(new Error('One account login timed out. Run `genesis login` again.'));
+        }
+        close();
+    }, timeout);
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        await new Promise((resolve, reject) => {
+            const aborted = () => { cleanup(); reject(new Error('One account login cancelled.')); };
+            const cleanup = () => { server.removeListener('error', error); controller.signal.removeEventListener('abort', aborted); };
+            const error = () => { cleanup(); reject(new Error('The registered One account callback port is unavailable. No other port was tried.')); };
+            server.once('error', error);
+            controller.signal.addEventListener('abort', aborted, { once: true });
+            if (controller.signal.aborted) {
+                aborted();
+                return;
+            }
+            server.listen({ port, host: '127.0.0.1', signal: controller.signal }, () => { cleanup(); resolve(); });
+        });
+        if (controller.signal.aborted || options.signal?.aborted)
+            throw new Error('One account login cancelled.');
+    }
+    catch (error) {
+        close();
+        throw error;
+    }
+    server.on('error', () => close());
+    const url = new URL('/v4/lifeid/start', LIFEID_ISSUER);
+    url.searchParams.set('product_id', registration.productId);
+    url.searchParams.set('return_path', '/');
+    url.searchParams.set('code_challenge', createHash('sha256').update(verifier).digest('base64url'));
+    url.searchParams.set('code_challenge_method', 'S256');
+    if (options.organizationHint)
+        url.searchParams.set('org_hint', options.organizationHint);
+    return { browserUrl: url.toString(), codeVerifier: verifier, registration: { ...registration }, code,
+        signal: controller.signal, close };
+}

package/dist/minds-owner.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { Genesis } from '@onesi/genesis';
+export declare function registerMindsOwner(minds: Command, client: () => Promise<Genesis>, emit: (value: unknown) => void, signal?: AbortSignal): void;

package/dist/minds-owner.js

@@ -0,0 +1,42 @@
+import { readFile, stat } from 'node:fs/promises';
+export function registerMindsOwner(minds, client, emit, signal) {
+    const intent = (command, revision = true) => {
+        command.requiredOption('--operation-id <uuid>', 'retain this non-nil UUID when reconciling the same intent');
+        if (revision)
+            command.requiredOption('--expected-version <integer>', 'current membership or attachment version; zero for first creation');
+        return command;
+    };
+    const version = (value) => {
+        if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)))
+            throw new Error('Expected version must be a nonnegative safe integer.');
+        return Number(value);
+    };
+    const body = (options) => ({ operationId: options.operationId, expectedVersion: version(options.expectedVersion) });
+    const groups = minds.command('groups').description('Canonical owner-managed groups; uses the original selected Console human session');
+    groups.command('list').action(async () => emit(await (await client()).minds.groups.list({ signal })));
+    intent(groups.command('create <name>'), false).action(async (name, options) => emit(await (await client()).minds.groups.create({ operationId: options.operationId, name }, { signal })));
+    const members = groups.command('members').description('Canonical group memberships and retained removal versions');
+    members.command('list <group_id>').action(async (group) => emit(await (await client()).minds.groups.members.list(group, { signal })));
+    intent(members.command('add <group_id> <agent_id>')).action(async (group, agent, options) => emit(await (await client()).minds.groups.members.add(group, { ...body(options), agentId: agent }, { signal })));
+    intent(members.command('remove <group_id> <agent_id>')).action(async (group, agent, options) => emit(await (await client()).minds.groups.members.remove(group, agent, body(options), { signal })));
+    const attachments = minds.command('attachments').description('Attach existing canonical agents or groups; never issues credentials');
+    attachments.command('list <mind_id>').action(async (mind) => emit(await (await client()).minds.attachments.list(mind, { signal })));
+    attachments.command('attach <mind_id>').requiredOption('--request-file <path>', 'closed JSON attachment intent with operationId, expectedVersion, subject, permissions and expiresAt')
+        .action(async (mind, options) => {
+        const metadata = await stat(options.requestFile);
+        if (!metadata.isFile() || metadata.size > 8192)
+            throw new Error('Attachment request must be at most 8 KiB.');
+        const bytes = await readFile(options.requestFile);
+        if (bytes.length > 8192)
+            throw new Error('Attachment request must be at most 8 KiB.');
+        let request;
+        try {
+            request = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        }
+        catch {
+            throw new Error('Attachment request must contain valid JSON.');
+        }
+        emit(await (await client()).minds.attachments.attach(mind, request, { signal }));
+    });
+    intent(attachments.command('detach <mind_id> <attachment_id>')).action(async (mind, attachment, options) => emit(await (await client()).minds.attachments.detach(mind, attachment, body(options), { signal })));
+}

package/dist/minds.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from 'commander';
+import type { Genesis } from '@onesi/genesis';
+export declare function registerMinds(program: Command, client: () => Promise<Genesis>, emit: (data: unknown) => void, agentClient?: () => Promise<Genesis>, signal?: AbortSignal, ownerClient?: () => Promise<Genesis>): void;

package/dist/minds.js

@@ -0,0 +1,90 @@
+import { readFile, stat } from 'node:fs/promises';
+import { registerMindsOwner } from './minds-owner.js';
+import { Option } from 'commander';
+export function registerMinds(program, client, emit, agentClient = client, signal, ownerClient = client) {
+    const minds = program.command('minds').description('Owned Minds and persisted memory; requires an admitted human Console Sandbox session');
+    registerMindsOwner(minds, ownerClient, emit, signal);
+    minds.command('list').option('--after <uuid>').option('--limit <number>').description('List real Minds and the current creation context fingerprint').action(async (options) => {
+        emit(await (await client()).minds.list({ ...(options.after ? { after: options.after } : {}), ...(options.limit ? { limit: Number(options.limit) } : {}) }));
+    });
+    minds.command('get <mind_id>').action(async (id) => emit(await (await client()).minds.get(id)));
+    minds.command('usage').description('Read selected-project native usage for an explicit window of at most 93 days')
+        .requiredOption('--from <timestamp>', 'RFC3339 window start')
+        .requiredOption('--to <timestamp>', 'RFC3339 window end')
+        .action(async (options) => emit(await (await client()).minds.usage({ from: options.from, to: options.to })));
+    minds.command('create <name>').description('Create a Sandbox Mind; Free/F1 by default or an admitted Pro profile; 202 means provisioning')
+        .requiredOption('--idempotency-key <uuid>', 'persist this UUID4 and retain it after an uncertain response')
+        .requiredOption('--context-sha256 <hash>', 'context_sha256 from the current minds list response')
+        .addOption(new Option('--plan <plan>', 'explicit plan; entitlement remains server-authorized').choices(['free', 'pro']))
+        .addOption(new Option('--profile-id <profile>', 'fixed native profile; Pro defaults to D1, Free accepts only F1').choices(['F1', 'D1', 'D2']))
+        .action(async (name, options) => emit(await (await client()).minds.create(name, { idempotencyKey: options.idempotencyKey, contextSha256: options.contextSha256, ...(options.plan === undefined ? {} : { plan: options.plan }), ...(options.profileId === undefined ? {} : { profileId: options.profileId }) })));
+    minds.command('resume <mind_id>').description('Resume the same Mind and retained volume; 202 means the operation is accepted')
+        .requiredOption('--expected-generation <number>', 'desired_generation from a fresh owned Mind read')
+        .requiredOption('--idempotency-key <uuid>', 'persist this UUID4 with the original generation after an uncertain response')
+        .addOption(new Option('--wake-reason <reason>', 'reason for this resume intent').choices(['manual', 'scheduled_job', 'webhook', 'memory_consolidation', 'activity']))
+        .action(async (id, options) => emit(await (await client()).minds.resume(id, Number(options.expectedGeneration), { idempotencyKey: options.idempotencyKey, ...(options.wakeReason === undefined ? {} : { wakeReason: options.wakeReason }) })));
+    minds.command('stop <mind_id>').description('Stop the same Mind without deleting its retained volume; 202 means accepted')
+        .requiredOption('--expected-generation <number>', 'desired_generation from a fresh owned Mind read')
+        .requiredOption('--idempotency-key <uuid>', 'persist this UUID4 and original generation; no automatic retry')
+        .action(async (id, options) => emit(await (await client()).minds.stop(id, Number(options.expectedGeneration), { idempotencyKey: options.idempotencyKey })));
+    const memory = minds.command('memory').description('Every operation selects one owned, ready Mind');
+    memory.command('insert <mind_id>').requiredOption('--event-file <path>', 'JSON event with id, content and timestamp; returned id is its storage UUID')
+        .action(async (id, options) => {
+        const metadata = await stat(options.eventFile);
+        if (!metadata.isFile() || metadata.size > 65_536)
+            throw new Error('Event file must be at most 64 KiB.');
+        const bytes = await readFile(options.eventFile);
+        if (bytes.length > 65_536)
+            throw new Error('Event file exceeds 64 KiB.');
+        const event = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        emit(await (await client()).minds.memory.insert(id, event));
+    });
+    memory.command('get <mind_id> <storage_id>').action(async (mind, storage) => emit(await (await client()).minds.memory.get(mind, storage)));
+    memory.command('update <mind_id> <storage_id>').requiredOption('--content-file <path>', 'JSON {event_id,content}; preserves stored metadata, never automatically retries')
+        .action(async (mind, storage, options) => {
+        const metadata = await stat(options.contentFile);
+        if (!metadata.isFile() || metadata.size > 65_536)
+            throw new Error('Update file must be at most 64 KiB.');
+        const bytes = await readFile(options.contentFile);
+        if (bytes.length > 65_536)
+            throw new Error('Update file exceeds 64 KiB.');
+        const body = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        emit(await (await client()).minds.memory.update(mind, storage, body));
+    });
+    memory.command('search <mind_id> <text>').option('--limit <number>', '1–100 results', '20').action(async (mind, text, options) => {
+        emit(await (await client()).minds.memory.search(mind, text, Number(options.limit)));
+    });
+    const agent = minds.command('agent').description('Use an existing agent credential; does not create an attachment or exchange a human session');
+    const agentMemory = agent.command('memory').description('Private or explicitly authorized group memory; requests are never automatically retried');
+    const scoped = (command) => command.option('--group <agp_id>', 'explicit canonical group; omit for private memory')
+        .option('--dpop-proof-file <path>', 'fresh DPoP proof for the controller capability method and URL');
+    const readBounded = async (path, limit) => {
+        const metadata = await stat(path);
+        if (!metadata.isFile() || metadata.size > limit)
+            throw new Error('Agent input file exceeds its byte limit.');
+        const bytes = await readFile(path);
+        if (bytes.length > limit)
+            throw new Error('Agent input file exceeds its byte limit.');
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    };
+    const agentOptions = async (options) => ({ signal,
+        ...(options.group === undefined ? {} : { group: options.group }),
+        ...(options.dpopProofFile === undefined ? {} : { dpopProof: await readBounded(options.dpopProofFile, 16_384) }),
+    });
+    scoped(agentMemory.command('insert <mind_id>').requiredOption('--event-file <path>', 'JSON event; retain the returned storage UUID'))
+        .action(async (mind, options) => {
+        const content = await readBounded(options.eventFile, 65_536);
+        let event;
+        try {
+            event = JSON.parse(content);
+        }
+        catch {
+            throw new Error('Agent event file must contain valid JSON.');
+        }
+        emit(await (await agentClient()).minds.agent.memory.insert(mind, event, await agentOptions(options)));
+    });
+    scoped(agentMemory.command('get <mind_id> <storage_id>'))
+        .action(async (mind, storage, options) => emit(await (await agentClient()).minds.agent.memory.get(mind, storage, await agentOptions(options))));
+    scoped(agentMemory.command('search <mind_id> <text>').option('--limit <number>', '1–100 results', '20'))
+        .action(async (mind, text, options) => emit(await (await agentClient()).minds.agent.memory.search(mind, text, Number(options.limit), await agentOptions(options))));
+}

package/dist/output.d.ts

@@ -0,0 +1,28 @@
+export interface Out {
+    log(s: string): void;
+    err(s: string): void;
+}
+export declare const stdio: Out;
+export declare const c: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    green: (s: string) => string;
+    yellow: (s: string) => string;
+    red: (s: string) => string;
+};
+/**
+ * Make server-provided text safe to print so it cannot drive the terminal: drop
+ * whole OSC sequences (OSC 8 hyperlinks included, BEL- or ST-terminated, 7- and
+ * 8-bit), CSI and other ESC sequences, then any remaining C0, DEL or C1 character,
+ * and finally bidi controls and invisible characters that can reorder or hide
+ * text (Trojan Source): LRE/RLE/PDF/LRO/RLO (U+202A-202E), LRI/RLI/FSI/PDI
+ * (U+2066-2069), ZWSP/ZWNJ/ZWJ/LRM/RLM (U+200B-200F), ALM (U+061C), BOM/ZWNBSP
+ * (U+FEFF), line/paragraph separators (U+2028-2029), word joiner and invisible
+ * operators (U+2060-2064), Mongolian vowel separator (U+180E), soft hyphen
+ * (U+00AD) and tag characters (U+E0000-E007F).
+ */
+export declare function safe(v: unknown): string;
+/** Render rows as an aligned table; every cell is passed through safe(). */
+export declare function table(rows: Record<string, unknown>[], cols: string[]): string;
+/** Pull the array out of the various list envelopes ({data}, {zones}, {records}, bare array). */
+export declare function listOf(x: any, ...keys: string[]): any[];

package/dist/output.js

@@ -0,0 +1,46 @@
+export const stdio = { log: (s) => process.stdout.write(s + '\n'), err: (s) => process.stderr.write(s + '\n') };
+const tty = () => !!process.stdout.isTTY && !process.env.NO_COLOR;
+export const c = {
+    bold: (s) => (tty() ? `\x1b[1m${s}\x1b[0m` : s),
+    dim: (s) => (tty() ? `\x1b[2m${s}\x1b[0m` : s),
+    green: (s) => (tty() ? `\x1b[32m${s}\x1b[0m` : s),
+    yellow: (s) => (tty() ? `\x1b[33m${s}\x1b[0m` : s),
+    red: (s) => (tty() ? `\x1b[31m${s}\x1b[0m` : s),
+};
+/**
+ * Make server-provided text safe to print so it cannot drive the terminal: drop
+ * whole OSC sequences (OSC 8 hyperlinks included, BEL- or ST-terminated, 7- and
+ * 8-bit), CSI and other ESC sequences, then any remaining C0, DEL or C1 character,
+ * and finally bidi controls and invisible characters that can reorder or hide
+ * text (Trojan Source): LRE/RLE/PDF/LRO/RLO (U+202A-202E), LRI/RLI/FSI/PDI
+ * (U+2066-2069), ZWSP/ZWNJ/ZWJ/LRM/RLM (U+200B-200F), ALM (U+061C), BOM/ZWNBSP
+ * (U+FEFF), line/paragraph separators (U+2028-2029), word joiner and invisible
+ * operators (U+2060-2064), Mongolian vowel separator (U+180E), soft hyphen
+ * (U+00AD) and tag characters (U+E0000-E007F).
+ */
+export function safe(v) {
+    return String(v)
+        .replace(/(?:\x1b\]|\x9d)[^\x07\x1b\x9c]*(?:\x07|\x1b\\|\x9c)?/g, '')
+        .replace(/(?:\x1b\[|\x9b)[\x30-\x3f]*[\x20-\x2f]*[\x40-\x7e]?/g, '')
+        .replace(/\x1b[\x20-\x2f]*[\x30-\x7e]?/g, '')
+        .replace(/[\x00-\x1f\x7f-\x9f]/g, '')
+        .replace(/[\u202a-\u202e\u2066-\u2069\u200b-\u200f\u061c\ufeff\u2028\u2029\u2060-\u2064\u180e\u00ad\u{e0000}-\u{e007f}]/gu, '');
+}
+/** Render rows as an aligned table; every cell is passed through safe(). */
+export function table(rows, cols) {
+    if (!rows.length)
+        return c.dim('(none)');
+    const cell = (v) => (v === undefined || v === null ? '' : safe(Array.isArray(v) ? v.join(',') : v));
+    const w = cols.map((k) => Math.max(k.length, ...rows.map((r) => cell(r[k]).length)));
+    const line = (vals) => vals.map((v, i) => v.padEnd(w[i])).join('  ').trimEnd();
+    return [c.bold(line(cols.map((k) => k.toUpperCase()))), ...rows.map((r) => line(cols.map((k) => cell(r[k]))))].join('\n');
+}
+/** Pull the array out of the various list envelopes ({data}, {zones}, {records}, bare array). */
+export function listOf(x, ...keys) {
+    if (Array.isArray(x))
+        return x;
+    for (const k of [...keys, 'data', 'items', 'results'])
+        if (Array.isArray(x?.[k]))
+            return x[k];
+    return [];
+}

package/dist/products.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from 'commander';
+import { type Genesis, type OperationId } from '@onesi/genesis';
+/** Command words -> operation. Positional arguments are the operation's path parameters, query
+ * parameters become options, a body comes from --body-file, and --idempotency-key carries the
+ * Idempotency-Key header (required where the service requires it). */
+export declare const PRODUCT_COMMANDS: Record<string, {
+    description: string;
+    commands: Record<string, OperationId>;
+}>;
+export declare function registerProducts(program: Command, dependencies: {
+    client: () => Promise<Genesis>;
+    emit: (data: unknown, pretty: () => string) => void;
+    signal?: AbortSignal;
+}): void;

package/dist/products.js

@@ -0,0 +1,85 @@
+import { idempotencyHeaders, operationTable } from '@onesi/genesis';
+import { readFunctionJson } from './function-input.js';
+/** Command words -> operation. Positional arguments are the operation's path parameters, query
+ * parameters become options, a body comes from --body-file, and --idempotency-key carries the
+ * Idempotency-Key header (required where the service requires it). */
+export const PRODUCT_COMMANDS = {
+    rigs: { description: 'Rigs: your desktops (read-only; One account login with a selected project)', commands: { list: 'rigs_listRigs' } },
+    panes: { description: 'Panes: your browsers (read-only; One account login with a selected project)', commands: { list: 'panes_listPanes' } },
+    shells: { description: 'Shells: your sandboxes (read-only; One account login with a selected project)', commands: { list: 'shells_listShells' } },
+    gears: { description: 'Gears: durable workflows, runs and signals', commands: {
+            'workflows list': 'gears_listWorkflows', 'workflows get': 'gears_getWorkflow', 'workflows register': 'gears_registerWorkflow',
+            'runs list': 'gears_listRuns', 'runs get': 'gears_getRun', 'runs history': 'gears_getRunHistory',
+            'runs start': 'gears_startRun', 'runs signal': 'gears_signalRun', records: 'gears_listOperationalRecords',
+        } },
+    lanes: { description: 'Lanes: agent context, cache, ledger and routing (Sandbox; One account login)', commands: {
+            'records get': 'lanes_getRecord', 'records write': 'lanes_writeRecord', 'records snapshot': 'lanes_snapshotRecords', 'records restore': 'lanes_restoreRecords',
+            retrieve: 'lanes_retrieve', 'frames create': 'lanes_createFrame', answer: 'lanes_answer',
+            'ledger frame': 'lanes_getLedgerFrame', 'ledger snapshot': 'lanes_snapshotLedger', 'ledger restore': 'lanes_restoreLedger',
+            'cache lookup': 'lanes_cacheLookup', 'cache write': 'lanes_cacheWrite', 'cache snapshot': 'lanes_snapshotCache', 'cache restore': 'lanes_restoreCache',
+            'recovery restore': 'lanes_recoveryRestore', 'tenant export': 'lanes_exportTenant', 'tenant delete': 'lanes_deleteTenant',
+            'policy evaluate': 'lanes_evaluatePolicy', 'foundry-routes enforce': 'lanes_enforceFoundryRoute',
+            'promotions list': 'lanes_listPromotionCandidates', 'promotions propose': 'lanes_proposePromotion', 'promotions review': 'lanes_reviewPromotion',
+            'operations records': 'lanes_listOperationalRecords', 'operations get': 'lanes_getOperation',
+        } },
+    flares: { description: 'Flares: agent notifications, conversations, commitments, presence, trust and choreography (Sandbox; One account login)', commands: {
+            list: 'flares_listFlares', get: 'flares_getFlare', send: 'flares_sendFlare', 'send-batch': 'flares_sendFlareBatch',
+            acknowledge: 'flares_acknowledgeFlare', act: 'flares_actOnFlare',
+            'conversations list': 'flares_listConversations', 'conversations get': 'flares_getConversation', 'conversations create': 'flares_createConversation',
+            'conversations send': 'flares_sendConversationMessage', 'conversations close': 'flares_closeConversation',
+            'commitments list': 'flares_listCommitments', 'commitments get': 'flares_getCommitment', 'commitments create': 'flares_createCommitment',
+            'commitments accept': 'flares_acceptCommitment', 'commitments start': 'flares_startCommitment', 'commitments progress': 'flares_reportCommitmentProgress',
+            'commitments fulfill': 'flares_fulfillCommitment', 'commitments fail': 'flares_failCommitment',
+            'presence heartbeat': 'flares_presenceHeartbeat', 'presence get': 'flares_getPresence',
+            'trust score': 'flares_getTrustScore', 'trust check': 'flares_checkTrust', 'trust endorsements': 'flares_listEndorsements',
+            'trust endorse': 'flares_createEndorsement', 'trust revoke': 'flares_revokeEndorsement',
+            'choreography workflows list': 'flares_listChoreographyWorkflows', 'choreography workflows create': 'flares_createChoreographyWorkflow',
+            'choreography workflows start': 'flares_startChoreographyExecution',
+            'choreography executions list': 'flares_listChoreographyExecutions', 'choreography executions get': 'flares_getChoreographyExecution',
+            'choreography executions complete-step': 'flares_completeChoreographyStep', 'choreography executions fail-step': 'flares_failChoreographyStep',
+            'choreography executions cancel': 'flares_cancelChoreographyExecution',
+        } },
+};
+const BODY_LIMIT = 1024 * 1024;
+const flag = (name) => name.replace(/_/g, '-').replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+/** Commander's option key for a flag: --recipient-did -> recipientDid. */
+const key = (name) => flag(name).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+export function registerProducts(program, dependencies) {
+    for (const [service, { description, commands }] of Object.entries(PRODUCT_COMMANDS)) {
+        const root = program.command(service).description(description);
+        const groups = new Map();
+        for (const [words, id] of Object.entries(commands)) {
+            const op = operationTable[id];
+            const parts = words.split(' ');
+            let parent = root;
+            for (let i = 0; i < parts.length - 1; i++) {
+                const key = parts.slice(0, i + 1).join(' ');
+                if (!groups.has(key))
+                    groups.set(key, parent.command(parts[i]));
+                parent = groups.get(key);
+            }
+            const bodyRequired = op.inputSchema.required.includes('body');
+            const command = parent.command([parts.at(-1), ...op.pathParams.map(p => `<${p}>`)].join(' ')).description(`${op.summary} (${op.method} ${op.path})`);
+            for (const q of op.queryParams)
+                command.option(`--${flag(q)} <value>`);
+            if (op.hasBody)
+                command[bodyRequired ? 'requiredOption' : 'option']('--body-file <path>', 'JSON request body, up to 1 MiB');
+            if (op.idempotencyKey === 'required')
+                command.requiredOption('--idempotency-key <key>', 'Stable key; reuse it to replay instead of acting twice');
+            else if (op.idempotencyKey)
+                command.option('--idempotency-key <key>', 'Optional stable key; a retry with it returns the original result');
+            command.action(async (...args) => {
+                const options = args[op.pathParams.length];
+                const input = Object.fromEntries(op.pathParams.map((p, i) => [p, args[i]]));
+                for (const q of op.queryParams)
+                    if (options[key(q)] !== undefined)
+                        input[q] = options[key(q)];
+                if (options.bodyFile)
+                    input.body = await readFunctionJson(options.bodyFile, BODY_LIMIT);
+                const headers = idempotencyHeaders(id, options.idempotencyKey);
+                const result = await (await dependencies.client()).request(id, input, { headers, signal: dependencies.signal });
+                dependencies.emit(result ?? { ok: true }, () => JSON.stringify(result ?? { ok: true }, null, 2));
+            });
+        }
+    }
+}

package/dist/relays-enrollment.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { Genesis } from '@onesi/genesis';
+export declare function registerRelaysEnrollment(relays: Command, client: () => Promise<Genesis>, emit: (value: unknown, pretty: () => string) => void): void;

package/dist/relays-enrollment.js

@@ -0,0 +1,7 @@
+export function registerRelaysEnrollment(relays, client, emit) {
+    const enrollment = relays.command('enrollment').description('Explicit empty Relays account for the current verified human selection');
+    for (const action of ['get', 'activate'])
+        enrollment.command(action).allowExcessArguments(false)
+            .description(action === 'get' ? 'Read status without creating an account' : 'Activate once; read status after any unconfirmed response')
+            .action(async () => { const value = await (await client()).relays.enrollment[action](); emit(value, () => JSON.stringify(value, null, 2)); });
+}

package/dist/runner.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+import type { Genesis } from '@onesi/genesis';
+/** Register only Runner commands. The authenticated credential determines org and subject. */
+export declare function registerRunner(program: Command, client: () => Promise<Genesis>, emit: (data: unknown, pretty: () => string) => void): void;

package/dist/runner.js

@@ -0,0 +1,55 @@
+/** Register only Runner commands. The authenticated credential determines org and subject. */
+export function registerRunner(program, client, emit) {
+    const runner = program.command('runner').description('Runner: agent task execution');
+    const output = (value) => emit(value, () => JSON.stringify(value, null, 2));
+    runner.command('permission-grant').description('Request only your current native human Sandbox execution permission; preserve operation/scope/expiry on retry')
+        .requiredOption('--organization <id>', 'current approved Life organization assertion')
+        .requiredOption('--project <id>', 'current approved project assertion')
+        .requiredOption('--workspace <id>', 'current approved workspace assertion')
+        .requiredOption('--operation-id <uuid>', 'stable canonical UUIDv4 for this immutable authorization operation')
+        .requiredOption('--request-id <uuid>', 'fresh canonical UUIDv4 correlation for this attempt')
+        .requiredOption('--expires-at-ms <ms>', 'exact retained future integer expiry, at most 30 minutes and current session/access expiry')
+        .action(async (o) => {
+        if (!/^[1-9]\d*$/.test(o.expiresAtMs) || !Number.isSafeInteger(Number(o.expiresAtMs)))
+            throw new TypeError('Runner permission expiry must be a positive safe integer literal');
+        const input = { schemaVersion: 1, organizationId: o.organization, projectId: o.project,
+            workspaceId: o.workspace, platformId: 'pf_console', fleetId: null, resourceEnvironment: 'sandbox',
+            operationId: o.operationId, requestId: o.requestId, expiresAtMs: Number(o.expiresAtMs) };
+        output(await (await client()).runner.permission.grant(input));
+    });
+    runner.command('catalog').description('Authorized workspaces and execution routes')
+        .action(async () => output(await (await client()).runner.catalog()));
+    const jobs = runner.command('jobs').description('Jobs belonging to your verified identity');
+    jobs.command('list', { isDefault: true }).description('Newest 100 jobs')
+        .action(async () => output(await (await client()).runner.jobs.list()));
+    jobs.command('start').description('Start a bounded task; refs must come from catalog')
+        .requiredOption('--task-id <id>', 'opaque task ID')
+        .requiredOption('--text <text>', 'task instructions (at most 32768 characters)')
+        .requiredOption('--workspace <ref>', 'authorized workspace key')
+        .requiredOption('--kind <kind>', 'external-harness or internal-model')
+        .requiredOption('--route <id>', 'authorized execution route')
+        .requiredOption('--idempotency-key <key>', 'stable key for retries of the same task')
+        .option('--duration-ms <ms>', 'maximum execution duration', '600000')
+        .option('--output-bytes <bytes>', 'maximum output size', '1048576')
+        .option('--max-events <count>', 'retained event limit', '200')
+        .action(async (o) => {
+        if (!['external-harness', 'internal-model'].includes(o.kind))
+            throw new TypeError('Runner kind must be external-harness or internal-model');
+        const body = {
+            task: { id: o.taskId, text: o.text }, workspaceRef: o.workspace,
+            executionRef: { kind: o.kind, routeId: o.route },
+            limits: { maxDurationMs: Number(o.durationMs), maxOutputBytes: Number(o.outputBytes), maxEvents: Number(o.maxEvents) },
+            idempotencyKey: o.idempotencyKey,
+        };
+        output(await (await client()).runner.jobs.start(body));
+    });
+    jobs.command('get <job_id>').description('Read the authoritative snapshot')
+        .action(async (id) => output(await (await client()).runner.jobs.get(id)));
+    jobs.command('events <job_id>').description('Read one event page; continue with nextAfterSeq while hasMore')
+        .option('--after-seq <seq>', 'exclusive event cursor', '0')
+        .action(async (id, o) => output(await (await client()).runner.jobs.events(id, Number(o.afterSeq))));
+    jobs.command('result <job_id>').description('Read the verified completed provider deliverable')
+        .action(async (id) => output(await (await client()).runner.jobs.result(id)));
+    jobs.command('cancel <job_id>').description('Request cancellation; then watch status and cleanupPending')
+        .action(async (id) => output(await (await client()).runner.jobs.cancel(id)));
+}

package/dist/secret-input.d.ts

@@ -0,0 +1,14 @@
+export interface SecretInputOptions {
+    file?: string;
+    stdin?: boolean;
+}
+export interface SecretInput {
+    name: string;
+    value: string;
+    description?: string;
+}
+/** Read plaintext only from an explicitly selected file or stdin, never argv. */
+export declare function readSecretInput(options: SecretInputOptions, limit: number): Promise<string>;
+export declare function validateSecretValue(value: string): string;
+export declare function validateSecret(input: unknown): SecretInput;
+export declare function parseSecretBatch(text: string): SecretInput[];