agentex-creator-sdk 1.0.0

package/dist/packages/sdk/src/bin/agentex.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCreatorCli } from '../cli.js';
+process.exitCode = await runCreatorCli(process.argv.slice(2), { env: process.env, stdout: text => process.stdout.write(text), stderr: text => process.stderr.write(text), stdin: process.stdin });

package/dist/packages/sdk/src/buyer-cli.d.ts

@@ -0,0 +1,10 @@
+export declare const BUYER_HELP = "AGENTEX buyer CLI 1.0.0 (reads AGENTEX_API_KEY and never prints it)\n  agentex-buyer key\n  agentex-buyer catalog [--q TEXT] [--chain solana|ethereum|base|robinhood] [--topic TOPIC] [--asset sol|usdc|eth]\n                        [--sort newest|name|price] [--limit N] [--cursor CURSOR]\n  agentex-buyer agent --listing LISTING_ID\n  agentex-buyer quote --listing LISTING_ID INPUT [--result-policy complete_only|canonical_metadata]\n  agentex-buyer accept --quote QUOTE_ID --contract-hash HASH --idempotency-key KEY --confirm\n  agentex-buyer research --listing LISTING_ID INPUT --max-debit AMOUNT --confirm [--idempotency-key KEY] [--timeout SECONDS]\n  agentex-buyer status --run RUN_ID [--wait] [--timeout SECONDS]\n  agentex-buyer report --run RUN_ID\n  agentex-buyer result --run RUN_ID [--out result.json]\n  agentex-buyer billing --run RUN_ID\n  agentex-buyer receipt --run RUN_ID [--wait] [--timeout SECONDS]\n  agentex-buyer cancel --run RUN_ID\n  agentex-buyer monitor create --file monitor.json | list | get --monitor ID | stop --monitor ID | notifications | ack --notification ID\n  agentex-buyer version\n\nINPUT is one of: --chain CHAIN --value NAME=VALUE ... (research workflows, for example --chain solana --value mint=<mint>),\n  --chain CHAIN --address ADDRESS (Token Researcher), or --input input.json (any agent's exact input object).\nCommon: [--api ORIGIN] (default AGENTEX_API_ORIGIN or https://agentex.sh),\n  [--asset sol|usdc|eth|ASSET_ID] (default AGENTEX_ASSET, else the key's own asset; SOL is solana:mainnet-beta/native).\n  --profile sim|local_custody|solana_sol|solana_usdc (or AGENTEX_PROFILE) is still accepted; --asset is preferred.\nA key pays in one asset: SOL or USDC keys belong to Solana accounts, ETH (Robinhood Chain) keys to EVM accounts.\naccept and research spend under the key's budget: review the quote, pass --confirm, and reuse the same idempotency key to retry.\nresearch refuses a quote above --max-debit, given in the payment currency (for example --max-debit 0.02 for 0.02 SOL).\n";
+export interface BuyerCliIO {
+    env: Record<string, string | undefined>;
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    fetch?: typeof fetch;
+    cwd?: string;
+}
+/** Runs one buyer subcommand and returns the process exit code. Output is JSON on stdout; errors are one line on stderr. */
+export declare function runBuyerCli(argv: readonly string[], io: BuyerCliIO): Promise<number>;

package/dist/packages/sdk/src/buyer-cli.js

@@ -0,0 +1,210 @@
+import { parseArgs } from 'node:util';
+import { z } from 'zod';
+import { AgentexApiError, createBuyerClient, DEFAULT_API_ORIGIN, IdempotencyKeySchema, parseAmount, workflowInput } from './buyer.js';
+import { readCreatorFile, writeCreatorFile } from './local.js';
+import { SDK_VERSION } from './version.js';
+export const BUYER_HELP = `AGENTEX buyer CLI ${SDK_VERSION} (reads AGENTEX_API_KEY and never prints it)
+  agentex-buyer key
+  agentex-buyer catalog [--q TEXT] [--chain solana|ethereum|base|robinhood] [--topic TOPIC] [--asset sol|usdc|eth]
+                        [--sort newest|name|price] [--limit N] [--cursor CURSOR]
+  agentex-buyer agent --listing LISTING_ID
+  agentex-buyer quote --listing LISTING_ID INPUT [--result-policy complete_only|canonical_metadata]
+  agentex-buyer accept --quote QUOTE_ID --contract-hash HASH --idempotency-key KEY --confirm
+  agentex-buyer research --listing LISTING_ID INPUT --max-debit AMOUNT --confirm [--idempotency-key KEY] [--timeout SECONDS]
+  agentex-buyer status --run RUN_ID [--wait] [--timeout SECONDS]
+  agentex-buyer report --run RUN_ID
+  agentex-buyer result --run RUN_ID [--out result.json]
+  agentex-buyer billing --run RUN_ID
+  agentex-buyer receipt --run RUN_ID [--wait] [--timeout SECONDS]
+  agentex-buyer cancel --run RUN_ID
+  agentex-buyer monitor create --file monitor.json | list | get --monitor ID | stop --monitor ID | notifications | ack --notification ID
+  agentex-buyer version
+
+INPUT is one of: --chain CHAIN --value NAME=VALUE ... (research workflows, for example --chain solana --value mint=<mint>),
+  --chain CHAIN --address ADDRESS (Token Researcher), or --input input.json (any agent's exact input object).
+Common: [--api ORIGIN] (default AGENTEX_API_ORIGIN or ${DEFAULT_API_ORIGIN}),
+  [--asset sol|usdc|eth|ASSET_ID] (default AGENTEX_ASSET, else the key's own asset; SOL is solana:mainnet-beta/native).
+  --profile sim|local_custody|solana_sol|solana_usdc (or AGENTEX_PROFILE) is still accepted; --asset is preferred.
+A key pays in one asset: SOL or USDC keys belong to Solana accounts, ETH (Robinhood Chain) keys to EVM accounts.
+accept and research spend under the key's budget: review the quote, pass --confirm, and reuse the same idempotency key to retry.
+research refuses a quote above --max-debit, given in the payment currency (for example --max-debit 0.02 for 0.02 SOL).
+`;
+const specifications = {
+    api: { type: 'string' }, profile: { type: 'string' }, asset: { type: 'string' }, listing: { type: 'string' }, chain: { type: 'string' }, address: { type: 'string' },
+    value: { type: 'string', multiple: true }, input: { type: 'string' }, 'result-policy': { type: 'string' }, quote: { type: 'string' }, 'contract-hash': { type: 'string' },
+    'idempotency-key': { type: 'string' }, confirm: { type: 'boolean' }, 'max-debit': { type: 'string' }, run: { type: 'string' }, wait: { type: 'boolean' }, timeout: { type: 'string' },
+    out: { type: 'string' }, monitor: { type: 'string' }, notification: { type: 'string' }, file: { type: 'string' }, q: { type: 'string' }, topic: { type: 'string' },
+    sort: { type: 'string' }, limit: { type: 'string' }, cursor: { type: 'string' }, help: { type: 'boolean' },
+};
+const common = ['api', 'profile', 'asset'];
+const inputOptions = ['chain', 'address', 'value', 'input'];
+const allowed = {
+    key: [], catalog: ['q', 'chain', 'topic', 'sort', 'limit', 'cursor'], agent: ['listing'], quote: ['listing', ...inputOptions, 'result-policy'],
+    accept: ['quote', 'contract-hash', 'idempotency-key', 'confirm'], research: ['listing', ...inputOptions, 'result-policy', 'max-debit', 'confirm', 'idempotency-key', 'timeout'],
+    status: ['run', 'wait', 'timeout'], report: ['run'], result: ['run', 'out'], billing: ['run'], receipt: ['run', 'wait', 'timeout'], cancel: ['run'],
+    'monitor create': ['file'], 'monitor list': [], 'monitor get': ['monitor'], 'monitor stop': ['monitor'], 'monitor notifications': [], 'monitor ack': ['notification'],
+};
+class CliUsageError extends Error {
+}
+const required = (value, name) => { if (!value)
+    throw new CliUsageError(`--${name} is required.`); return value; };
+const scalar = (raw) => raw === 'true' ? true : raw === 'false' ? false : /^-?(0|[1-9][0-9]{0,14})$/.test(raw) ? Number(raw) : raw;
+const seconds = (raw) => raw === undefined ? undefined : Number(z.string().regex(/^[1-9][0-9]{0,4}$/).parse(raw)) * 1000;
+/** The run input from --input FILE, --chain with --value NAME=VALUE pairs (a research workflow), or --chain with --address (Token Researcher). */
+async function quoteInput(values, cwd) {
+    const forms = [values.input !== undefined, values.value !== undefined, values.address !== undefined].filter(Boolean).length;
+    if (forms !== 1)
+        throw new CliUsageError('Give the run input one way: --input input.json, --chain with --value NAME=VALUE, or --chain with --address.');
+    if (values.input !== undefined) {
+        if (values.chain !== undefined)
+            throw new CliUsageError('--input already contains the chain; drop --chain.');
+        const raw = await readCreatorFile(values.input, cwd);
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            throw new CliUsageError('--input must be a JSON object.');
+        return raw;
+    }
+    const chain = required(values.chain, 'chain');
+    if (values.address !== undefined)
+        return { chain, address: values.address };
+    const entries = values.value.map(pair => {
+        const match = /^([A-Za-z][A-Za-z0-9_]{0,63})=(.{1,500})$/.exec(pair);
+        if (!match)
+            throw new CliUsageError('Each --value is NAME=VALUE, for example --value mint=<mint address>.');
+        return [match[1], scalar(match[2])];
+    });
+    if (new Set(entries.map(([name]) => name)).size !== entries.length)
+        throw new CliUsageError('Each --value name may appear once.');
+    return workflowInput(z.enum(['ethereum', 'base', 'robinhood', 'solana']).parse(chain), Object.fromEntries(entries));
+}
+/** Runs one buyer subcommand and returns the process exit code. Output is JSON on stdout; errors are one line on stderr. */
+export async function runBuyerCli(argv, io) {
+    try {
+        const [first, second] = argv;
+        if (!first || first === 'help' || first === '--help') {
+            io.stdout(BUYER_HELP);
+            return 0;
+        }
+        if (first === 'version' || first === '--version') {
+            io.stdout(`${SDK_VERSION}\n`);
+            return 0;
+        }
+        const command = first === 'monitor' ? `monitor ${second ?? ''}` : first;
+        if (!Object.hasOwn(allowed, command))
+            throw new CliUsageError('Unsupported buyer command. Run `agentex-buyer help`.');
+        const { values, tokens } = parseArgs({ args: argv.slice(first === 'monitor' ? 2 : 1), options: specifications, strict: true, allowPositionals: false, tokens: true });
+        const names = tokens.filter(token => token.kind === 'option').map(token => token.name);
+        const repeatable = new Set(['value']);
+        if (new Set(names.filter(name => !repeatable.has(name))).size !== names.filter(name => !repeatable.has(name)).length || names.some(name => name !== 'help' && !common.includes(name) && !allowed[command].includes(name)))
+            throw new CliUsageError('Duplicate or unsupported options for this command.');
+        if (values.help) {
+            io.stdout(BUYER_HELP);
+            return 0;
+        }
+        const apiKey = io.env.AGENTEX_API_KEY;
+        if (!apiKey)
+            throw new CliUsageError('Set AGENTEX_API_KEY to a key created at https://agentex.sh/developers.');
+        const profileText = values.profile ?? io.env.AGENTEX_PROFILE;
+        const profile = profileText === undefined || profileText === '' ? undefined : z.enum(['sim', 'local_custody', 'solana_sol', 'solana_usdc']).parse(profileText);
+        const asset = values.asset ?? (io.env.AGENTEX_ASSET || undefined);
+        const client = createBuyerClient({ origin: values.api ?? (io.env.AGENTEX_API_ORIGIN || DEFAULT_API_ORIGIN), apiKey, ...(profile ? { profile } : {}), ...(asset ? { assetId: asset } : {}), ...(io.fetch ? { fetch: io.fetch } : {}) });
+        const timeoutMs = seconds(values.timeout);
+        let output;
+        switch (command) {
+            case 'key':
+                output = { key: await client.key() };
+                break;
+            case 'catalog':
+                output = await client.listAgents({ ...(values.q ? { q: values.q } : {}), ...(values.chain ? { chain: values.chain } : {}), ...(values.topic ? { topic: values.topic } : {}),
+                    ...(asset ? { assetId: asset } : {}), ...(values.sort ? { sort: z.enum(['newest', 'name', 'price']).parse(values.sort) } : {}), ...(values.cursor ? { cursor: values.cursor } : {}),
+                    ...(values.limit ? { limit: Number(z.string().regex(/^[1-9][0-9]?$/).parse(values.limit)) } : {}) });
+                break;
+            case 'agent':
+                output = { agent: await client.getAgent(required(values.listing, 'listing')) };
+                break;
+            case 'quote': {
+                const quote = await client.createQuote({ listingId: required(values.listing, 'listing'), input: await quoteInput(values, io.cwd),
+                    ...(values['result-policy'] ? { resultPolicy: z.enum(['complete_only', 'canonical_metadata']).parse(values['result-policy']) } : {}) });
+                output = { quote, next: `Review the quote, then: agentex-buyer accept --quote ${quote.id} --contract-hash ${quote.contractHash} --idempotency-key <stable-key> --confirm` };
+                break;
+            }
+            case 'accept':
+                if (!values.confirm)
+                    throw new CliUsageError('Accepting spends under the key budget. Review the quote and pass --confirm.');
+                output = await client.acceptQuote({ quoteId: required(values.quote, 'quote'), contractHash: required(values['contract-hash'], 'contract-hash'), idempotencyKey: IdempotencyKeySchema.parse(required(values['idempotency-key'], 'idempotency-key')) });
+                break;
+            case 'research': {
+                if (!values.confirm)
+                    throw new CliUsageError('research accepts a quote and spends under the key budget. Pass --max-debit and --confirm.');
+                const payment = await client.paymentAsset();
+                if (payment.decimals === null)
+                    throw new CliUsageError('This asset has unknown decimals; use quote and accept instead.');
+                const maxDebitAtomic = parseAmount(required(values['max-debit'], 'max-debit'), payment.decimals);
+                const outcome = await client.research({ listingId: required(values.listing, 'listing'), input: await quoteInput(values, io.cwd), maxDebitAtomic,
+                    ...(values['result-policy'] ? { resultPolicy: z.enum(['complete_only', 'canonical_metadata']).parse(values['result-policy']) } : {}),
+                    ...(values['idempotency-key'] ? { idempotencyKey: IdempotencyKeySchema.parse(values['idempotency-key']) } : {}), ...(timeoutMs ? { wait: { timeoutMs } } : {}) });
+                const { raw: _raw, ...report } = outcome.report;
+                output = { run: { id: outcome.run.id, status: outcome.run.status }, quote: { id: outcome.quote.id, maximumBuyerDebitAtomic: outcome.quote.maximumBuyerDebitAtomic, expiresAt: outcome.quote.expiresAt },
+                    payment: outcome.payment, idempotencyKey: outcome.idempotencyKey, report, next: `agentex-buyer receipt --run ${outcome.run.id} --wait` };
+                break;
+            }
+            case 'status':
+                output = values.wait ? await client.waitForRun(required(values.run, 'run'), timeoutMs ? { timeoutMs } : {}) : await client.getRun(required(values.run, 'run'));
+                break;
+            case 'report': {
+                const { raw: _raw, ...report } = await client.getReport(required(values.run, 'run'));
+                output = report;
+                break;
+            }
+            case 'result': {
+                const result = await client.getResult(required(values.run, 'run'));
+                if (values.out) {
+                    await writeCreatorFile(values.out, result, io.cwd);
+                    output = { output: 'written', artifactId: result.artifactId, status: result.run.status };
+                }
+                else
+                    output = result;
+                break;
+            }
+            case 'billing':
+                output = await client.getBilling(required(values.run, 'run'));
+                break;
+            case 'receipt':
+                output = await client.getReceipt(required(values.run, 'run'), values.wait ? { waitForSettlement: timeoutMs ? { timeoutMs } : true } : {});
+                break;
+            case 'cancel':
+                output = { run: await client.cancelRun(required(values.run, 'run')) };
+                break;
+            case 'monitor create':
+                output = await client.createMonitor(await readCreatorFile(required(values.file, 'file'), io.cwd));
+                break;
+            case 'monitor list':
+                output = { monitors: await client.listMonitors() };
+                break;
+            case 'monitor get':
+                output = await client.getMonitor(required(values.monitor, 'monitor'));
+                break;
+            case 'monitor stop':
+                output = { monitor: await client.stopMonitor(required(values.monitor, 'monitor')) };
+                break;
+            case 'monitor notifications':
+                output = { notifications: await client.listNotifications() };
+                break;
+            case 'monitor ack':
+                output = { notification: await client.acknowledgeNotification(required(values.notification, 'notification')) };
+                break;
+        }
+        io.stdout(`${JSON.stringify(output, null, 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof AgentexApiError)
+            io.stderr(`Buyer command failed (${error.status === null ? error.code : `HTTP ${error.status} ${error.code}`}): ${error.message}${error.runId ? ` Run ${error.runId}.` : ''}\n`);
+        else if (error instanceof CliUsageError)
+            io.stderr(`${error.message}\n`);
+        else if (error instanceof z.ZodError)
+            io.stderr('Validation failed: an option or JSON file does not match the buyer contract.\n');
+        else
+            io.stderr('Buyer command failed. Check options, JSON files (inside the working directory, never overwritten) and the API origin.\n');
+        return 1;
+    }
+}