agentex-creator-sdk 1.0.0

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

@@ -0,0 +1,441 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { verifyWebhookSignature, WEBHOOK_EVENT_ID_HEADER } from '../../monitoring/src/delivery.js';
+import { AgentexApiError, isAgentexApiError } from './errors.js';
+import { assetIdOf, describeAsset, formatAmount, profileForAsset, railPath, resolveAssetId } from './rails.js';
+import { readReport } from './report.js';
+import { SDK_VERSION } from './version.js';
+export { AgentexApiError, isAgentexApiError } from './errors.js';
+export * from './rails.js';
+export * from './report.js';
+/**
+ * Typed buyer SDK for the AGENTEX buyer API (https://agentex.sh). It sends only `Authorization: Bearer <key>`, never cookies, never follows
+ * redirects and never includes the API key in an error. Plain HTTP is allowed only to loopback origins. Payment rails are chosen by asset id
+ * (SOL first; USDC on Solana; ETH on Robinhood Chain), and an API key is bound to one of them.
+ */
+export const BUYER_SDK_VERSION = SDK_VERSION;
+/** The production API origin. The buyer API is served from the site's own origin. */
+export const DEFAULT_API_ORIGIN = 'https://agentex.sh';
+export const API_KEY_PATTERN = /^agx_(test|live)_[A-Za-z0-9_-]{43}$/;
+export const IdempotencyKeySchema = z.string().min(8).max(128).regex(/^[a-zA-Z0-9_-]+$/);
+const Hash = z.string().regex(/^[a-f0-9]{64}$/);
+const Uuid = z.uuid();
+const ATOMIC = /^(0|[1-9][0-9]{0,77})$/;
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+const MAX_RETRY_AFTER_MS = 30_000;
+/** Marketplace topics (the catalog's controlled vocabulary; `topic` filter). */
+export const CATALOG_TOPICS = Object.freeze(['token-intelligence', 'contract-forensics', 'wallet-intelligence', 'transaction-safety', 'monitoring', 'defi', 'liquidity', 'lending-yield',
+    'staking', 'stablecoins', 'governance', 'treasuries', 'rwa', 'bridges', 'chain-activity', 'launches', 'nfts', 'security']);
+/** Builds a research-workflow input: `workflowInput('solana', { mint })`. */
+export function workflowInput(chain, values) { return { workflow: 'agentex.workflow.v1', chain, values }; }
+const statusKinds = { 400: 'invalid_input', 401: 'unauthorized', 403: 'forbidden', 404: 'not_found', 408: 'network', 409: 'conflict', 410: 'gone', 413: 'invalid_input', 429: 'rate_limited', 503: 'unavailable' };
+const TERMINAL = new Set(['succeeded', 'partial', 'failed', 'cancelled']);
+/** An exact origin. HTTPS anywhere; plain HTTP only on loopback, so a bearer key never crosses a network in clear text. */
+export function buyerApiOrigin(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new AgentexApiError('invalid_input', null, 'invalid_origin', 'The API origin is not a valid URL.', false);
+    }
+    const loopback = ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname);
+    if (!['http:', 'https:'].includes(url.protocol) || (url.protocol === 'http:' && !loopback) || url.username || url.password || (url.pathname !== '/' && url.pathname !== '') || url.search || url.hash)
+        throw new AgentexApiError('invalid_input', null, 'invalid_origin', 'The API origin must be an exact HTTPS origin, or HTTP on loopback.', false);
+    return url.origin;
+}
+/** The offer a listing makes in one asset (an asset id or `sol`, `usdc`, `eth`), or undefined when it does not accept that asset. */
+export function offerFor(agent, assetId) {
+    const id = resolveAssetId(assetId);
+    return agent.offers.find(offer => offer.pricing.assetId === id);
+}
+const aborted = () => new AgentexApiError('aborted', null, 'aborted', 'The request was aborted by the caller.', false);
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(aborted());
+            return;
+        }
+        const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(); }, ms);
+        const onAbort = () => { clearTimeout(timer); reject(aborted()); };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function retryAfter(headers) {
+    const raw = headers.get('retry-after');
+    if (!raw)
+        return null;
+    const seconds = Number(raw);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return Math.round(seconds * 1000);
+    const date = Date.parse(raw);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : null;
+}
+function errorBody(data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return null;
+    const value = data;
+    const nested = value.error;
+    if (nested && typeof nested === 'object' && !Array.isArray(nested)) {
+        const error = nested;
+        if (typeof error.code === 'string' && typeof error.message === 'string')
+            return { code: error.code.slice(0, 100), message: error.message.slice(0, 2000) };
+    }
+    // The site's edge answers some failures (unavailable service, oversized or slow bodies) as { error?: string, message: string }.
+    if (typeof value.message === 'string')
+        return { code: typeof nested === 'string' ? nested.slice(0, 100) : 'http_error', message: value.message.slice(0, 2000) };
+    return null;
+}
+export function createBuyerClient(options) {
+    const origin = buyerApiOrigin(options.origin ?? DEFAULT_API_ORIGIN);
+    if (typeof options.apiKey !== 'string' || !API_KEY_PATTERN.test(options.apiKey))
+        throw new AgentexApiError('unauthorized', null, 'invalid_api_key', 'An AGENTEX API key (agx_live_... or agx_test_...) is required. Create one at https://agentex.sh/developers.', false);
+    const apiKey = options.apiKey;
+    const doFetch = options.fetch ?? fetch;
+    const defaultAsset = options.assetId === undefined ? undefined : resolveAssetId(options.assetId);
+    if (options.profile && defaultAsset && profileForAsset(defaultAsset) !== options.profile)
+        throw new AgentexApiError('invalid_input', null, 'profile_asset_mismatch', `Profile ${options.profile} does not pay in ${defaultAsset}.`, false);
+    let profile = options.profile ?? (defaultAsset ? profileForAsset(defaultAsset) : undefined);
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    const maxRetries = Math.max(0, Math.min(options.maxRetries ?? 2, 5));
+    const retryDelayMs = Math.max(0, options.retryDelayMs ?? 250);
+    const id = (value, label = 'ID') => { if (typeof value !== 'string' || !Uuid.safeParse(value).success)
+        throw new AgentexApiError('invalid_input', null, 'invalid_input', `${label} must be a UUID.`, false); return value; };
+    const assetOption = (value) => value === undefined ? defaultAsset : resolveAssetId(value);
+    async function once(method, path, body, signal) {
+        if (signal?.aborted)
+            throw aborted();
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const combined = signal ? AbortSignal.any([timeout, signal]) : timeout;
+        const failed = (error) => {
+            if (isAgentexApiError(error))
+                throw error;
+            if (signal?.aborted)
+                throw aborted();
+            if (timeout.aborted)
+                throw new AgentexApiError('network', null, 'timeout', `${method} ${path} timed out after ${timeoutMs} ms.`, true);
+            throw new AgentexApiError('network', null, 'network', `${method} ${path} could not reach the API.`, true);
+        };
+        let response;
+        try {
+            response = await doFetch(`${origin}${path}`, { method, redirect: 'error', credentials: 'omit', signal: combined,
+                headers: { authorization: `Bearer ${apiKey}`, accept: 'application/json', ...(body === undefined ? {} : { 'content-type': 'application/json' }) }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+        }
+        catch (error) {
+            return failed(error);
+        }
+        const tooLarge = () => new AgentexApiError('invalid_response', response.status, 'invalid_response', 'The API response exceeds the SDK size limit.', false);
+        if (Number(response.headers.get('content-length') ?? 0) > MAX_RESPONSE_BYTES) {
+            await response.body?.cancel().catch(() => undefined);
+            throw tooLarge();
+        }
+        const reader = response.body?.getReader();
+        const chunks = [];
+        let size = 0;
+        try {
+            while (reader) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                size += value.byteLength;
+                if (size > MAX_RESPONSE_BYTES)
+                    throw tooLarge();
+                chunks.push(value);
+            }
+        }
+        catch (error) {
+            return failed(error);
+        }
+        finally {
+            await reader?.cancel().catch(() => undefined);
+        }
+        let data = null;
+        if (size) {
+            const bytes = new Uint8Array(size);
+            let offset = 0;
+            for (const chunk of chunks) {
+                bytes.set(chunk, offset);
+                offset += chunk.byteLength;
+            }
+            try {
+                data = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+            }
+            catch {
+                // A failure page that is not JSON (for example a proxy's HTML 502) is still classified by its status below.
+                if (response.ok)
+                    throw new AgentexApiError('invalid_response', response.status, 'invalid_response', `${method} ${path} returned a non-JSON response.`, false);
+                data = null;
+            }
+        }
+        if (!response.ok) {
+            const error = errorBody(data);
+            const kind = statusKinds[response.status] ?? (response.status >= 500 ? 'server' : 'invalid_response');
+            const retryable = kind === 'rate_limited' || kind === 'network' || (response.status >= 500 && response.status !== 503);
+            throw new AgentexApiError(kind, response.status, error?.code ?? 'http_error', error?.message ?? `${method} ${path} failed with HTTP ${response.status}.`, retryable, retryAfter(response.headers));
+        }
+        return { status: response.status, headers: response.headers, data };
+    }
+    /**
+     * GETs and idempotent POSTs (idempotency-keyed acceptance and monitor creation; cancel, stop and acknowledge) retry network failures, 5xx
+     * other than 503, and 429 with backoff. Quote creation is never retried: a lost quote simply expires unused.
+     */
+    async function request(method, path, requestOptions = {}) {
+        const retry = requestOptions.retry ?? method === 'GET';
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await once(method, path, requestOptions.body, requestOptions.signal);
+            }
+            catch (error) {
+                if (!retry || !isAgentexApiError(error) || !error.retryable || attempt >= maxRetries)
+                    throw error;
+                if (error.retryAfterMs !== null && error.retryAfterMs > MAX_RETRY_AFTER_MS)
+                    throw error;
+                await sleep(Math.max(error.retryAfterMs ?? 0, Math.min(retryDelayMs * 2 ** attempt, 8_000)), requestOptions.signal);
+            }
+        }
+    }
+    const get = async (path, signal) => (await request('GET', path, { signal })).data;
+    const catalogQuery = (input) => {
+        const params = new URLSearchParams();
+        const { assetId, ...rest } = input;
+        if (assetId !== undefined && rest.profile === undefined)
+            params.set('profile', profileForAsset(assetId));
+        for (const [name, value] of Object.entries(rest))
+            if (value !== undefined)
+                params.set(name, String(value));
+        const text = params.toString();
+        return text ? `?${text}` : '';
+    };
+    let grant;
+    /** The key's grant, read once: its profile and asset never change. */
+    const keyGrant = () => grant ??= get('/v1/buyer/key').then(data => data.key, (error) => { grant = undefined; throw error; });
+    async function resolveProfile(assetId) {
+        if (assetId)
+            return profileForAsset(assetId);
+        if (profile)
+            return profile;
+        profile = (await keyGrant()).profile;
+        return profile;
+    }
+    const solanaRail = (value) => value === 'solana_sol' || value === 'solana_usdc';
+    async function waitUntil(read, done, wait, label) {
+        const deadline = Date.now() + (wait.timeoutMs ?? 300_000);
+        let interval = Math.max(50, wait.intervalMs ?? 1000);
+        const longest = Math.max(interval, wait.maxIntervalMs ?? 10_000);
+        const factor = Math.max(1, wait.backoff ?? 1.5);
+        for (;;) {
+            if (wait.signal?.aborted)
+                throw aborted();
+            let value;
+            let readOk = false;
+            try {
+                value = await read();
+                readOk = true;
+            }
+            catch (error) {
+                if (!isAgentexApiError(error) || !error.retryable || Date.now() >= deadline)
+                    throw error;
+            }
+            if (readOk && done(value))
+                return value;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                throw new AgentexApiError('timeout', null, 'wait_timeout', `${label} did not finish before the wait timeout. Waiting again is safe.`, true);
+            await sleep(Math.min(interval, remaining), wait.signal);
+            interval = Math.min(longest, Math.ceil(interval * factor));
+        }
+    }
+    const client = {
+        origin,
+        /** The explicit or derived payment profile; undefined until the key's own profile has been read. */
+        get profile() { return profile; },
+        /** The profile this client quotes and pays with: the explicit one, the asset's, or the key's own (one `GET /v1/buyer/key`). */
+        resolveProfile: () => resolveProfile(defaultAsset),
+        /** The asset this client pays in: the client's `assetId`, else the key's own asset. */
+        async paymentAsset() { return describeAsset(defaultAsset ?? (await keyGrant()).assetId); },
+        /** The key's own scopes, asset, expiry and `remainingSpendAtomic`. Any valid key may read it. */
+        async key(call = {}) { const key = (await get('/v1/buyer/key', call.signal)).key; profile ??= key.profile; return key; },
+        /** One page of public agents. Pass `nextCursor` back as `cursor`; `null` means the last page. Needs `catalog:read`. */
+        async listAgents(input = {}, call = {}) { return get(`/v1/public/agents${catalogQuery(input)}`, call.signal); },
+        /** Iterates pages until `nextCursor` is null, bounded by `maxPages` (default 20). */
+        async *agents(input = {}, maxPages = 20) {
+            let cursor;
+            for (let page = 0; page < maxPages; page++) {
+                const result = await client.listAgents({ ...input, ...(cursor ? { cursor } : {}) });
+                yield* result.agents;
+                if (!result.nextCursor)
+                    return;
+                cursor = result.nextCursor;
+            }
+        },
+        /** Permissions, limits, input fields, offers (one per payment rail) and limitations of one listing. */
+        async getAgent(listingId, call = {}) { return (await get(`/v1/public/agents/${id(listingId, 'listingId')}`, call.signal)).agent; },
+        /** The listings this key can buy with its rail (full manifests and tariffs), with the rail's pricing policy. */
+        async listings(input = {}) {
+            const assetId = assetOption(input.assetId);
+            const current = await resolveProfile(assetId);
+            const query = assetId && current !== 'sim' ? `?assetId=${encodeURIComponent(assetId)}` : '';
+            return get(`${railPath(current)}/catalog${query}`, input.signal);
+        },
+        /**
+         * Creates a server-priced quote on the rail of `assetId` (or the client's default, or the key's own asset). It reserves nothing and expires
+         * after 240 seconds. Never retried. When an asset was named, a quote priced in any other asset is refused with `asset_mismatch`.
+         */
+        async createQuote(input) {
+            const listingId = id(input.listingId, 'listingId');
+            const assetId = assetOption(input.assetId);
+            const current = await resolveProfile(assetId);
+            const body = { listingId, input: input.input, resultPolicy: input.resultPolicy ?? 'complete_only', ...(assetId && solanaRail(current) ? { assetId } : {}) };
+            const quote = (await request('POST', `${railPath(current)}/quotes`, { body, retry: false, signal: input.signal })).data.quote;
+            const quoted = assetIdOf(quote.asset);
+            if (assetId && quoted && quoted !== assetId)
+                throw new AgentexApiError('conflict', null, 'asset_mismatch', `The server quoted in ${quoted}, not the requested ${assetId}. Nothing was reserved; the quote expires unused.`, false);
+            return quote;
+        },
+        /**
+         * Consents to one exact quote. The contract hash must be the one returned by createQuote. One idempotency key is used for all retries
+         * of this call (generated if omitted and returned), so a lost response never reserves twice. Pass the quote's `assetId` when the client
+         * has no default asset and the key's rail is not the quote's.
+         */
+        async acceptQuote(input) {
+            const idempotencyKey = IdempotencyKeySchema.parse(input.idempotencyKey ?? `sdk-${randomUUID()}`);
+            if (!Hash.safeParse(input.contractHash).success)
+                throw new AgentexApiError('invalid_input', null, 'invalid_input', 'contractHash must be the 64-character hex hash from the quote.', false);
+            const quoteId = id(input.quoteId, 'quoteId');
+            const current = await resolveProfile(assetOption(input.assetId));
+            const result = await request('POST', `${railPath(current)}/quotes/${quoteId}/accept`, { body: { acceptedContractHash: input.contractHash, idempotencyKey }, retry: true, signal: input.signal });
+            return { ...result.data, idempotencyKey };
+        },
+        /** Run status and its latest events (at most 250). */
+        async getRun(runId, call = {}) { return get(`/v1/runs/${id(runId, 'runId')}`, call.signal); },
+        /**
+         * Polls until the run leaves queued/running, with backoff (1 s growing to 10 s by default). Transient failures keep polling; a timeout
+         * throws a retryable `timeout` error (`wait_timeout`) and an aborted signal throws `aborted`. The run itself is never affected.
+         */
+        async waitForRun(runId, wait = {}) {
+            id(runId, 'runId');
+            return waitUntil(() => client.getRun(runId, wait.signal ? { signal: wait.signal } : {}), state => { wait.onStatus?.(state); return TERMINAL.has(state.run.status); }, wait, `Run ${runId}`);
+        },
+        /** Typed findings, evidence and sources of a finished run. A run without a report yet is a `conflict` (`report_unavailable`). */
+        async getReport(runId, call = {}) {
+            const state = await client.getRun(runId, call);
+            if (!state.run.output)
+                throw new AgentexApiError('conflict', null, 'report_unavailable', 'This run does not have a report yet. Wait for it to finish first.', false);
+            return readReport(state.run.output);
+        },
+        /** The canonical stored export (run, immutable version, events). A run without a report yet is a 409 `conflict`. */
+        async getResult(runId, call = {}) {
+            const response = await request('GET', `/v1/runs/${id(runId, 'runId')}/export`, { signal: call.signal });
+            return { artifactId: response.headers.get('x-agentex-artifact-id'), ...response.data };
+        },
+        /** Cancels a run; repeating it returns the current state. Cancellation charges only execution already incurred. */
+        async cancelRun(runId, call = {}) { return (await request('POST', `/v1/runs/${id(runId, 'runId')}/cancel`, { retry: true, signal: call.signal })).data.run; },
+        /** Reservation and settlement of a run on its rail (the client's default asset or the key's own). */
+        async getBilling(runId, input = {}) {
+            const current = await resolveProfile(assetOption(input.assetId));
+            return get(`${railPath(current)}/runs/${id(runId, 'runId')}/billing`, input.signal);
+        },
+        /**
+         * The run's billing with its payment asset and a formatted charge. The asset comes from `quote` when given, else `assetId`, else the key's
+         * own asset (a key only sees runs paid in its asset). `waitForSettlement` polls until the reservation settles.
+         */
+        async getReceipt(runId, input = {}) {
+            id(runId, 'runId');
+            const assetId = (input.quote ? assetIdOf(input.quote.asset) : null) ?? (input.assetId !== undefined ? resolveAssetId(input.assetId) : (await keyGrant()).assetId);
+            const read = () => client.getBilling(runId, { assetId, ...(input.signal ? { signal: input.signal } : {}) });
+            const wait = input.waitForSettlement === true ? {} : input.waitForSettlement || null;
+            const billing = wait ? await waitUntil(read, value => value.status === 'settled', { ...(input.signal ? { signal: input.signal } : {}), ...wait }, `Settlement of run ${runId}`) : await read();
+            const payment = describeAsset(assetId);
+            const settlement = billing.settlement;
+            return { runId: billing.runId, quoteId: billing.quoteId, reservationId: billing.reservationId, status: billing.status, outcome: settlement?.outcome ?? null, payment,
+                maximumDebitAtomic: input.quote?.maximumBuyerDebitAtomic ?? null, chargedAtomic: settlement?.chargedAtomic ?? null,
+                charged: settlement ? formatAmount(settlement.chargedAtomic, payment) : null,
+                fees: settlement ? { creatorFeeAtomic: settlement.creatorFeeAtomic, platformFeeAtomic: settlement.platformFeeAtomic, executionChargeAtomic: settlement.executionChargeAtomic } : null,
+                pendingReason: billing.pendingReason, billing };
+        },
+        /**
+         * Quote, consent check, accept and wait in one call. It needs a consent bound (`maxDebitAtomic`, `approve`, or both) and refuses, without
+         * accepting, a quote above it. A wait failure after acceptance carries `runId` so you can resume with `waitForRun`.
+         */
+        async research(input) {
+            if (input.maxDebitAtomic === undefined && !input.approve)
+                throw new AgentexApiError('refused', null, 'consent_required', 'research() spends from your balance: pass maxDebitAtomic (the most one run may reserve) or an approve(quote) callback.', false);
+            if (input.maxDebitAtomic !== undefined && !ATOMIC.test(input.maxDebitAtomic))
+                throw new AgentexApiError('invalid_input', null, 'invalid_amount', 'maxDebitAtomic must be a non-negative integer atomic amount.', false);
+            if (input.idempotencyKey !== undefined)
+                IdempotencyKeySchema.parse(input.idempotencyKey);
+            const signal = input.signal ? { signal: input.signal } : {};
+            const quote = await client.createQuote({ listingId: input.listingId, input: input.input, ...(input.resultPolicy ? { resultPolicy: input.resultPolicy } : {}), ...(input.assetId !== undefined ? { assetId: input.assetId } : {}), ...signal });
+            const assetId = assetIdOf(quote.asset) ?? assetOption(input.assetId) ?? null;
+            const payment = assetId ? describeAsset(assetId) : null;
+            const amount = (value) => payment ? formatAmount(value, payment) : `${value} atomic units`;
+            if (input.maxDebitAtomic !== undefined && BigInt(quote.maximumBuyerDebitAtomic) > BigInt(input.maxDebitAtomic))
+                throw new AgentexApiError('refused', null, 'quote_exceeds_limit', `The quote can reserve up to ${amount(quote.maximumBuyerDebitAtomic)}, above your limit of ${amount(input.maxDebitAtomic)}. Nothing was accepted.`, false);
+            if (input.approve && !(await input.approve(quote)))
+                throw new AgentexApiError('refused', null, 'not_approved', 'The quote was not approved. Nothing was accepted.', false);
+            const acceptance = await client.acceptQuote({ quoteId: quote.id, contractHash: quote.contractHash, ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}), ...(assetId ? { assetId } : {}), ...signal });
+            let state;
+            try {
+                state = await client.waitForRun(acceptance.run.id, { ...input.wait, ...(input.wait?.signal ?? input.signal ? { signal: input.wait?.signal ?? input.signal } : {}) });
+            }
+            catch (error) {
+                if (isAgentexApiError(error))
+                    error.runId = acceptance.run.id;
+                throw error;
+            }
+            return { quote, acceptance, idempotencyKey: acceptance.idempotencyKey, run: state.run, events: state.events, report: readReport(state.run.output), payment };
+        },
+        /** Creates a monitor on your own Watchtower version. The webhook secret is returned only on first creation (null on replay). */
+        async createMonitor(input, call = {}) {
+            const body = { ...input, idempotencyKey: IdempotencyKeySchema.parse(input.idempotencyKey ?? `sdk-${randomUUID()}`) };
+            const response = await request('POST', '/v1/monitors', { body, retry: true, signal: call.signal });
+            return { ...response.data, idempotencyKey: body.idempotencyKey };
+        },
+        async listMonitors(call = {}) { return (await get('/v1/monitors', call.signal)).monitors; },
+        async getMonitor(monitorId, call = {}) { return get(`/v1/monitors/${id(monitorId, 'monitorId')}`, call.signal); },
+        async stopMonitor(monitorId, call = {}) { return (await request('POST', `/v1/monitors/${id(monitorId, 'monitorId')}/stop`, { retry: true, signal: call.signal })).data.monitor; },
+        async listNotifications(call = {}) { return (await get('/v1/notifications', call.signal)).notifications; },
+        async acknowledgeNotification(notificationId, call = {}) { return (await request('POST', `/v1/notifications/${id(notificationId, 'notificationId')}/ack`, { retry: true, signal: call.signal })).data.notification; },
+    };
+    return client;
+}
+export function createMemoryReplayStore(maximumEntries = 10_000) {
+    const seen = new Map();
+    return { claim(deliveryId, expiresAt) {
+            const now = Date.now();
+            for (const [key, expiry] of seen) {
+                if (expiry > now && seen.size < maximumEntries)
+                    break;
+                seen.delete(key);
+            }
+            if ((seen.get(deliveryId) ?? 0) > now)
+                return false;
+            seen.set(deliveryId, expiresAt.getTime());
+            return true;
+        } };
+}
+export const WebhookPayloadSchema = z.looseObject({ type: z.enum(['monitor.event', 'monitor.event.retracted']), eventId: Uuid, monitorId: Uuid, chain: z.string(), status: z.enum(['active', 'retracted']) });
+/**
+ * Verifies a monitor webhook with the monitoring package's HMAC check (signature, event ID and a 5-minute timestamp window), then
+ * claims the delivery ID in `replay` so a duplicate callback is rejected. Pass the raw request body exactly as received.
+ * Signature failure is checked first, so a forged request can never consume a genuine delivery ID.
+ */
+export async function verifyWebhook(input) {
+    const headers = Object.fromEntries(Object.entries(input.headers).map(([name, value]) => [name.toLowerCase(), value]));
+    const tolerance = input.toleranceSeconds ?? 300;
+    const now = input.now ?? new Date();
+    if (!input.secret || !verifyWebhookSignature(input.secret, { headers, body: input.body }, { now, toleranceSeconds: tolerance }))
+        return { ok: false, reason: 'invalid_signature' };
+    let payload;
+    try {
+        payload = WebhookPayloadSchema.parse(JSON.parse(input.body));
+    }
+    catch {
+        return { ok: false, reason: 'invalid_payload' };
+    }
+    const header = headers[WEBHOOK_EVENT_ID_HEADER];
+    const deliveryId = Array.isArray(header) ? header[0] : header;
+    if (!(await input.replay.claim(deliveryId, new Date(now.getTime() + 2 * tolerance * 1000))))
+        return { ok: false, reason: 'duplicate' };
+    return { ok: true, deliveryId, payload };
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Creator CLI for the published `agentex` bin (N01). Behaviour matches the repository script `scripts/agentex.ts`: every file stays
+ * inside the working directory, outputs never overwrite, `submit` is loopback-only with a development session, and errors never
+ * echo arguments, server bodies or session material.
+ */
+export declare const CREATOR_HELP = "AGENTEX creator CLI 1.0.0\n  scaffold --id ID --name NAME [--chains ethereum,base] [--description TEXT]\n           [--read-owner true|false] [--read-proxy-slots true|false]\n           [--max-rpc N] [--max-duration-ms N] [--max-output-bytes N] --out manifest.json\n  validate --file manifest.json [--out validation.json]\n  test --file manifest.json [--out evaluation.json]\n  estimate --file manifest.json [--out estimate.json]\n  pack --file manifest.json --out package.json\n  submit --file package.json --api http://127.0.0.1:4000 --origin http://localhost:3000\n         --key IDEMPOTENCY_KEY [--session-stdin] [--out imported.json]\n  version\n\nFiles must be regular JSON inside the current directory; output parents must exist and files are never overwritten.\nscaffold, validate, test, estimate and pack are offline. submit imports a private creator version into a local development API\nusing AGENTEX_SESSION_TOKEN or --session-stdin; it does not publish, approve, quote or purchase it.\nBuyer commands against https://agentex.sh use the separate agentex-buyer bin with a scoped AGENTEX_API_KEY.\n";
+export interface CreatorCliIo {
+    env: Record<string, string | undefined>;
+    stdout(text: string): void;
+    stderr(text: string): void;
+    stdin?: AsyncIterable<Buffer | string>;
+}
+/** Runs one creator CLI command and returns the exit code. */
+export declare function runCreatorCli(argv: readonly string[], io: CreatorCliIo): Promise<number>;

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

@@ -0,0 +1,149 @@
+import { parseArgs } from 'node:util';
+import { z } from 'zod';
+import { ImportKeySchema, SDK_VERSION, estimateManifest, parseCreatorPackage, prepareCreatorPackage, scaffoldTokenResearcher, submitCreatorPackage, testManifest, validateManifest } from './index.js';
+import { createLocalImportTransport, loopbackOrigin, readCreatorFile, writeCreatorFile } from './local.js';
+/**
+ * Creator CLI for the published `agentex` bin (N01). Behaviour matches the repository script `scripts/agentex.ts`: every file stays
+ * inside the working directory, outputs never overwrite, `submit` is loopback-only with a development session, and errors never
+ * echo arguments, server bodies or session material.
+ */
+export const CREATOR_HELP = `AGENTEX creator CLI ${SDK_VERSION}
+  scaffold --id ID --name NAME [--chains ethereum,base] [--description TEXT]
+           [--read-owner true|false] [--read-proxy-slots true|false]
+           [--max-rpc N] [--max-duration-ms N] [--max-output-bytes N] --out manifest.json
+  validate --file manifest.json [--out validation.json]
+  test --file manifest.json [--out evaluation.json]
+  estimate --file manifest.json [--out estimate.json]
+  pack --file manifest.json --out package.json
+  submit --file package.json --api http://127.0.0.1:4000 --origin http://localhost:3000
+         --key IDEMPOTENCY_KEY [--session-stdin] [--out imported.json]
+  version
+
+Files must be regular JSON inside the current directory; output parents must exist and files are never overwritten.
+scaffold, validate, test, estimate and pack are offline. submit imports a private creator version into a local development API
+using AGENTEX_SESSION_TOKEN or --session-stdin; it does not publish, approve, quote or purchase it.
+Buyer commands against https://agentex.sh use the separate agentex-buyer bin with a scoped AGENTEX_API_KEY.
+`;
+const specifications = {
+    id: { type: 'string' }, name: { type: 'string' }, description: { type: 'string' }, chains: { type: 'string' },
+    'read-owner': { type: 'string' }, 'read-proxy-slots': { type: 'string' }, 'max-rpc': { type: 'string' },
+    'max-duration-ms': { type: 'string' }, 'max-output-bytes': { type: 'string' }, file: { type: 'string' }, out: { type: 'string' },
+    api: { type: 'string' }, origin: { type: 'string' }, key: { type: 'string' }, 'session-stdin': { type: 'boolean' }, help: { type: 'boolean' },
+};
+const allowed = {
+    scaffold: ['id', 'name', 'description', 'chains', 'read-owner', 'read-proxy-slots', 'max-rpc', 'max-duration-ms', 'max-output-bytes', 'out'],
+    validate: ['file', 'out'], test: ['file', 'out'], estimate: ['file', 'out'], pack: ['file', 'out'],
+    submit: ['file', 'out', 'api', 'origin', 'key', 'session-stdin'],
+};
+const boolean = (raw, fallback) => raw === undefined ? fallback : z.enum(['true', 'false']).parse(raw) === 'true';
+const integer = (raw) => raw === undefined ? undefined : Number(z.string().regex(/^(0|[1-9][0-9]*)$/).parse(raw));
+async function sessionFromStdin(stdin) {
+    let size = 0;
+    const chunks = [];
+    const reading = (async () => {
+        for await (const chunk of stdin) {
+            const bytes = Buffer.from(chunk);
+            size += bytes.length;
+            if (size > 128)
+                throw new Error('Session input exceeds its size limit.');
+            chunks.push(bytes);
+        }
+        return Buffer.concat(chunks).toString('utf8').trim();
+    })();
+    let timer;
+    const timeout = new Promise((_resolve, reject) => { timer = setTimeout(() => reject(new Error('Session input timed out.')), 5_000); });
+    try {
+        return await Promise.race([reading, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Runs one creator CLI command and returns the exit code. */
+export async function runCreatorCli(argv, io) {
+    let exitCode = 0;
+    try {
+        const command = argv[0];
+        if (!command || command === '--help' || command === 'help') {
+            io.stdout(CREATOR_HELP);
+            return 0;
+        }
+        if (command === 'version' || command === '--version') {
+            io.stdout(`${SDK_VERSION}\n`);
+            return 0;
+        }
+        if (!Object.hasOwn(allowed, command))
+            throw new Error('Unsupported CLI command.');
+        const { values, tokens } = parseArgs({ args: argv.slice(1), options: specifications, strict: true, allowPositionals: false, tokens: true });
+        const names = tokens.filter(token => token.kind === 'option').map(token => token.name);
+        if (new Set(names).size !== names.length || names.some(name => name !== 'help' && !allowed[command].includes(name)))
+            throw new Error('Duplicate or unsupported command options.');
+        if (values.help) {
+            io.stdout(CREATOR_HELP);
+            return 0;
+        }
+        let result;
+        if (command === 'scaffold') {
+            if (!values.id || !values.name || !values.out)
+                throw new Error('Scaffold requires id, name and out.');
+            const limits = { ...(values['max-rpc'] === undefined ? {} : { maximumRpcCalls: integer(values['max-rpc']) }),
+                ...(values['max-duration-ms'] === undefined ? {} : { maximumDurationMs: integer(values['max-duration-ms']) }),
+                ...(values['max-output-bytes'] === undefined ? {} : { maximumOutputBytes: integer(values['max-output-bytes']) }) };
+            result = scaffoldTokenResearcher({ id: values.id, name: values.name, ...(values.description ? { description: values.description } : {}),
+                ...(values.chains ? { chains: z.array(z.enum(['ethereum', 'base'])).parse(values.chains.split(',')) } : {}),
+                ...(values['read-owner'] === undefined && values['read-proxy-slots'] === undefined ? {} : { researchPolicy: { readOwner: boolean(values['read-owner'], true), readProxySlots: boolean(values['read-proxy-slots'], true) } }),
+                ...(Object.keys(limits).length ? { limits } : {}) });
+        }
+        else {
+            if (!values.file)
+                throw new Error('This command requires a JSON file.');
+            if ((command === 'pack' && !values.out) || (command === 'submit' && (!values.api || !values.origin || !values.key)))
+                throw new Error('Required command options are missing.');
+            // Reject endpoint/key misuse before reading a session or making a request.
+            if (command === 'submit') {
+                loopbackOrigin(values.api);
+                loopbackOrigin(values.origin);
+                ImportKeySchema.parse(values.key);
+            }
+            const raw = await readCreatorFile(values.file);
+            if (command === 'validate') {
+                const manifest = validateManifest(raw);
+                result = { status: 'valid', manifestHash: prepareCreatorPackage(manifest).manifestHash, executable: 'bounded-token-researcher' };
+            }
+            else if (command === 'estimate')
+                result = estimateManifest(raw);
+            else if (command === 'pack')
+                result = prepareCreatorPackage(raw);
+            else if (command === 'test') {
+                const evaluation = await testManifest(raw);
+                result = { ...evaluation, fixtures: evaluation.fixtures.map(({ report: _report, ...fixture }) => fixture) };
+                if (evaluation.status !== 'passed')
+                    exitCode = 1;
+            }
+            else {
+                const envelope = parseCreatorPackage(raw);
+                if (values['session-stdin'] && io.env.AGENTEX_SESSION_TOKEN)
+                    throw new Error('Choose one session input source.');
+                const sessionToken = values['session-stdin'] ? await sessionFromStdin(io.stdin ?? process.stdin) : io.env.AGENTEX_SESSION_TOKEN;
+                if (!sessionToken)
+                    throw new Error('An authenticated development session is required.');
+                result = await submitCreatorPackage(envelope, { idempotencyKey: values.key, transport: createLocalImportTransport({ api: values.api, origin: values.origin, sessionToken }) });
+            }
+        }
+        if (values.out) {
+            await writeCreatorFile(values.out, result);
+            io.stdout(`${JSON.stringify({ command, output: 'written', status: exitCode ? 'failed' : 'ok' })}\n`);
+        }
+        else
+            io.stdout(`${JSON.stringify(result, null, 2)}\n`);
+        return exitCode;
+    }
+    catch (error) {
+        // Do not echo argv, package labels, server response bodies, cookie values, URLs with credentials or stacks.
+        if (error instanceof z.ZodError)
+            io.stderr('Validation failed: the supplied JSON or command options do not match the supported creator contract.\n');
+        else
+            io.stderr('Command failed. Check required options, bounded JSON files, existing output paths and local authentication; no files are overwritten.\n');
+        return 1;
+    }
+}

package/dist/packages/sdk/src/errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Every failure the buyer client raises is an `AgentexApiError`. `status` is the HTTP status (null when no response arrived), `code` is the
+ * server's error code (or an SDK code such as `network`, `timeout`, `wait_timeout`, `aborted`, `consent_required`, `asset_mismatch`), and the
+ * message is safe to show a user: it never contains the API key.
+ */
+export type BuyerErrorKind = 'invalid_input' | 'unauthorized' | 'forbidden' | 'not_found' | 'conflict' | 'gone' | 'rate_limited' | 'unavailable' | 'server' | 'network' | 'invalid_response'
+/** A wait (run or settlement) passed its deadline. Waiting again is safe. */
+ | 'timeout'
+/** The caller's AbortSignal fired. */
+ | 'aborted'
+/** The SDK refused to spend: no consent bound was given, or the quote exceeded it. Nothing was reserved. */
+ | 'refused';
+export declare class AgentexApiError extends Error {
+    readonly kind: BuyerErrorKind;
+    readonly status: number | null;
+    readonly code: string;
+    /** True when repeating the same call can succeed (network failures, 5xx other than 503, rate limits, timeouts). */
+    readonly retryable: boolean;
+    /** Server-suggested wait before retrying (from `Retry-After`), when one was sent. */
+    readonly retryAfterMs: number | null;
+    readonly name = "AgentexApiError";
+    constructor(kind: BuyerErrorKind, status: number | null, code: string, message: string, 
+    /** True when repeating the same call can succeed (network failures, 5xx other than 503, rate limits, timeouts). */
+    retryable: boolean, 
+    /** Server-suggested wait before retrying (from `Retry-After`), when one was sent. */
+    retryAfterMs?: number | null);
+    /** Set when the failure happened after a run was accepted (`research()` waiting), so the caller can resume with `waitForRun(runId)`. */
+    runId?: string;
+}
+/** Type guard for `catch (error)` blocks. */
+export declare function isAgentexApiError(error: unknown): error is AgentexApiError;