@botanary/agent 0.1.0-alpha.1

package/dist/signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.js","sourceRoot":"","sources":["../src/signer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAqBrD,wGAAwG;AACxG,MAAM,UAAU,qBAAqB,CAAC,OAKrC,EAAE,UAAoD,EAAE;IACvD,MAAM,QAAQ,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS;QACvE,WAAW,EAAE,iBAAiB,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,UAAU;QACvF,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC;IAC7D,OAAO;QACL,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,GAAG,QAAQ,EAAE,CAAC;QACrC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,CAAC;QACjD,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;KACzC,CAAC;AACJ,CAAC"}

package/dist/transport.d.ts

@@ -0,0 +1,13 @@
+/** Injection seam for an existing host transport. It receives only public payloads and agent tokens. */
+export interface AgentTransport {
+    get<T>(path: string, token?: string): Promise<T>;
+    post<T>(path: string, body: unknown, token?: string): Promise<T>;
+}
+/** No mutation retries. A failed relay must be reconciled using its existing operation/hash. */
+export declare class AgentApiClient implements AgentTransport {
+    #private;
+    constructor(baseUrl: string, fetchImpl?: typeof fetch);
+    get<T>(path: string, token?: string): Promise<T>;
+    post<T>(path: string, body: unknown, token?: string): Promise<T>;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAMA,wGAAwG;AACxG,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACjD,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAClE;AAED,gGAAgG;AAChG,qBAAa,cAAe,YAAW,cAAc;;gBAEvC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,KAAa;IAS5D,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAChD,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CAuDjE"}

package/dist/transport.js

@@ -0,0 +1,135 @@
+import createClient from 'openapi-fetch';
+import { AGENT_ROUTES } from './generated/routes.js';
+import { canonicalizeHttpPath } from './http-path.js';
+import { BotanaryApiError } from './errors.js';
+/** No mutation retries. A failed relay must be reconciled using its existing operation/hash. */
+export class AgentApiClient {
+    #client;
+    constructor(baseUrl, fetchImpl = fetch) {
+        const url = new URL(baseUrl);
+        if (url.username || url.password || url.search || url.hash || url.pathname !== '/' ||
+            (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))) {
+            throw new Error('Agent API origin must be HTTPS, or HTTP on loopback.');
+        }
+        this.#client = createClient({ baseUrl: url.origin + '/v1', fetch: boundedFetch(fetchImpl) });
+    }
+    get(path, token) { return this.#request('get', path, undefined, token); }
+    post(path, body, token) { return this.#request('post', path, body, token); }
+    async #request(method, path, body, token) {
+        const canonical = canonicalizeHttpPath(path);
+        if (!canonical?.path.startsWith('/v1/'))
+            throw new Error('Invalid agent API path.');
+        if (token !== undefined && !/^ags_[a-f0-9]{64}$/.test(token))
+            throw new Error('Expected an agent session credential.');
+        const cleanPath = canonical.path.slice(3);
+        const route = AGENT_ROUTES.find(row => row.method === method &&
+            new RegExp('^' + row.path.replace(/\{[^}]+\}/g, '[A-Za-z0-9_-]+') + '$').test(cleanPath));
+        if (!route)
+            throw new Error('This route is outside the reviewed agent API.');
+        const parameters = {};
+        route.path.split('/').forEach((part, index) => {
+            if (part.startsWith('{'))
+                parameters[part.slice(1, -1)] = cleanPath.split('/')[index];
+        });
+        const query = Object.fromEntries(new URLSearchParams(canonical.query));
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 30_000);
+        try {
+            const result = await this.#client.request(method, route.path, {
+                params: { path: parameters, query },
+                ...(body === undefined ? {} : { body }),
+                headers: token ? { authorization: `Bearer ${token}` } : {},
+                credentials: 'omit', redirect: 'error', cache: 'no-store', signal: controller.signal,
+                parseAs: 'text',
+            });
+            const response = result.response;
+            let data = result.error;
+            if (response.ok) {
+                try {
+                    data = result.data ? JSON.parse(result.data) : {};
+                }
+                catch {
+                    throw new Error('Invalid JSON response.');
+                }
+            }
+            if (!response.ok) {
+                const error = record(record(data)?.error);
+                const message = typeof error?.message === 'string' ? error.message : `Agent request failed with ${response.status}.`;
+                const redacted = message.replace(/(?:bsk_(?:test|live)|ags|dcs|dca|dcr)_[A-Za-z0-9_-]+/g, '[redacted]').replace(/0x[a-fA-F0-9]{64,}/g, '[redacted]');
+                const retry = response.headers.get('retry-after');
+                const retrySeconds = retry && /^\d+(?:\.\d+)?$/.test(retry) ? Number(retry) : null;
+                // Keep only actionable, non-secret fields. The response body and request never enter errors.
+                const details = record(error?.details);
+                const safeDetails = details && Object.fromEntries(Object.entries(details).filter(([key, value]) => ['missingModule', 'declineReason', 'chainId'].includes(key) && (typeof value === 'number' || (typeof value === 'string' && /^[a-zA-Z0-9_-]{1,100}$/.test(value)))));
+                const failure = new BotanaryApiError(redacted.slice(0, 1000), response.status, safeDetails, retrySeconds);
+                failure.requestId = safeId(response.headers.get('x-request-id'));
+                failure.code = safeId(error?.code) ?? 'http_error';
+                failure.ambiguous = method === 'post' && response.status >= 500;
+                throw failure;
+            }
+            return data;
+        }
+        catch (error) {
+            if (error instanceof BotanaryApiError)
+                throw error;
+            const failure = new BotanaryApiError('The agent request did not complete. Check the existing operation before retrying.', 0);
+            failure.code = controller.signal.aborted ? 'timeout' : 'transport_error';
+            failure.ambiguous = method === 'post';
+            throw failure;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : null;
+}
+function safeId(value) {
+    return typeof value === 'string' && /^[a-zA-Z0-9_-]{1,128}$/.test(value) && !/^(?:ags|bsk|dcs|dca|dcr)_/.test(value) ? value : undefined;
+}
+function boundedFetch(fetchImpl) {
+    return async (input, init) => {
+        const request = input instanceof Request ? input : new Request(input, init);
+        const signal = request.signal;
+        let cancel = () => { };
+        const aborted = new Promise((_, reject) => {
+            cancel = () => reject(new Error('Request aborted.'));
+            if (signal.aborted)
+                cancel();
+            else
+                signal.addEventListener('abort', cancel, { once: true });
+        });
+        let reader;
+        try {
+            const response = await Promise.race([fetchImpl(request), aborted]);
+            if (!response.body)
+                return response;
+            reader = response.body.getReader();
+            const chunks = [];
+            let size = 0;
+            while (true) {
+                const part = await Promise.race([reader.read(), aborted]);
+                if (part.done)
+                    break;
+                size += part.value.byteLength;
+                if (size > 4 * 1024 * 1024)
+                    throw new Error('Response too large.');
+                chunks.push(part.value);
+            }
+            const bytes = new Uint8Array(size);
+            let offset = 0;
+            for (const chunk of chunks) {
+                bytes.set(chunk, offset);
+                offset += chunk.byteLength;
+            }
+            return new Response(bytes, { status: response.status, statusText: response.statusText, headers: response.headers });
+        }
+        finally {
+            signal.removeEventListener('abort', cancel);
+            if (reader)
+                void reader.cancel().catch(() => { });
+        }
+    };
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAQ/C,gGAAgG;AAChG,MAAM,OAAO,cAAc;IAChB,OAAO,CAAC;IACjB,YAAY,OAAe,EAAE,YAA0B,KAAK;QAC1D,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QAC7B,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,QAAQ,KAAK,GAAG;YAC9E,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7H,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,YAAY,CAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,GAAG,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACtG,CAAC;IAED,GAAG,CAAI,IAAY,EAAE,KAAc,IAAgB,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACzG,IAAI,CAAI,IAAY,EAAE,IAAa,EAAE,KAAc,IAAgB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAErH,KAAK,CAAC,QAAQ,CAAI,MAAsB,EAAE,IAAY,EAAE,IAAa,EAAE,KAAc;QACnF,MAAM,SAAS,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QACpF,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QACvH,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM;YAC1D,IAAI,MAAM,CAAC,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,gBAAgB,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;QAC5F,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;QAC7E,MAAM,UAAU,GAA2B,EAAE,CAAC;QAC9C,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;YAC5C,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAE,CAAC;QACzF,CAAC,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,eAAe,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACvE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,CAAC;QAC7D,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,IAAa,EAAE;gBACrE,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE;gBACnC,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;gBACvC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE;gBAC1D,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM;gBACpF,OAAO,EAAE,MAAM;aACP,CAA4D,CAAC;YACvE,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;YACjC,IAAI,IAAI,GAAY,MAAM,CAAC,KAAK,CAAC;YACjC,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;gBAChB,IAAI,CAAC;oBAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAc,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC;oBAAC,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;gBAAC,CAAC;YAC3H,CAAC;YACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;gBAC1C,MAAM,OAAO,GAAG,OAAO,KAAK,EAAE,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,6BAA6B,QAAQ,CAAC,MAAM,GAAG,CAAC;gBACrH,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,uDAAuD,EAAE,YAAY,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,YAAY,CAAC,CAAC;gBACrJ,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;gBAClD,MAAM,YAAY,GAAG,KAAK,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;gBACnF,6FAA6F;gBAC7F,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;gBACvC,MAAM,WAAW,GAAG,OAAO,IAAI,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAChG,CAAC,eAAe,EAAE,eAAe,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBACtK,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;gBAC1G,OAAO,CAAC,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC;gBACjE,OAAO,CAAC,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,YAAY,CAAC;gBACnD,OAAO,CAAC,SAAS,GAAG,MAAM,KAAK,MAAM,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,CAAC;gBAChE,MAAM,OAAO,CAAC;YAChB,CAAC;YACD,OAAO,IAAS,CAAC;QACnB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,gBAAgB;gBAAE,MAAM,KAAK,CAAC;YACnD,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC,mFAAmF,EAAE,CAAC,CAAC,CAAC;YAC7H,OAAO,CAAC,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC;YACzE,OAAO,CAAC,SAAS,GAAG,MAAM,KAAK,MAAM,CAAC;YACtC,MAAM,OAAO,CAAC;QAChB,CAAC;gBAAS,CAAC;YAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QAAC,CAAC;IACtC,CAAC;CACF;AAED,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAgC,CAAC,CAAC,CAAC,IAAI,CAAC;AACxH,CAAC;AACD,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,2BAA2B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3I,CAAC;AAED,SAAS,YAAY,CAAC,SAAuB;IAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QAC3B,MAAM,OAAO,GAAG,KAAK,YAAY,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC5E,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC9B,IAAI,MAAM,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;QACtB,MAAM,OAAO,GAAG,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;YAC/C,MAAM,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC,CAAC;YACrD,IAAI,MAAM,CAAC,OAAO;gBAAE,MAAM,EAAE,CAAC;;gBAAM,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9F,CAAC,CAAC,CAAC;QACH,IAAI,MAA2D,CAAC;QAChE,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;YACnE,IAAI,CAAC,QAAQ,CAAC,IAAI;gBAAE,OAAO,QAAQ,CAAC;YACpC,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACnC,MAAM,MAAM,GAAiB,EAAE,CAAC;YAChC,IAAI,IAAI,GAAG,CAAC,CAAC;YACb,OAAO,IAAI,EAAE,CAAC;gBACZ,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;gBAC1D,IAAI,IAAI,CAAC,IAAI;oBAAE,MAAM;gBACrB,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC;gBAC9B,IAAI,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI;oBAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;gBACnE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,MAAM,GAAG,CAAC,CAAC;YACf,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;gBAAC,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC;YAAC,CAAC;YACrF,OAAO,IAAI,QAAQ,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QACtH,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YAC5C,IAAI,MAAM;gBAAE,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACnD,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/validation.d.ts

@@ -0,0 +1,15 @@
+import type { Hex } from 'viem';
+import type { AgentIdentity } from './signer.js';
+import type { ApiCallRequirementsReady, UnsignedUserOp } from './views.js';
+export declare function invalidResponse(): never;
+export declare function record(value: unknown): Record<string, unknown>;
+export declare function hex(value: unknown, bytes?: number): asserts value is Hex;
+export declare function resourceId(value: unknown): asserts value is string;
+export declare function publicIdentity(value: unknown): AgentIdentity;
+/** The public v0.7 contract permits decimal or hex integer quantities. Bytes remain hex-only. */
+export declare function userOpQuantity(value: unknown, bits?: number): bigint;
+export declare function unsignedUserOp(value: unknown): UnsignedUserOp;
+export declare function readyRequirement(value: unknown): Pick<ApiCallRequirementsReady, 'payload' | 'authorization' | 'index' | 'validator'>;
+/** Bind a recovery response to the requested handle; never treat provider success as payment proof. */
+export declare function apiCallStatus(value: unknown, requirementId: string): Record<string, unknown>;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAEhC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,wBAAwB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE3E,wBAAgB,eAAe,IAAI,KAAK,CAIvC;AACD,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAG9D;AACD,wBAAgB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,GAAG,CAExE;AACD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CAElE;AAID,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAU5D;AACD,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,SAAM,GAAG,MAAM,CAKjE;AACD,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAU7D;AACD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC,wBAAwB,EAAE,SAAS,GAAG,eAAe,GAAG,OAAO,GAAG,WAAW,CAAC,CAWpI;AAED,uGAAuG;AACvG,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAY5F"}

package/dist/validation.js

@@ -0,0 +1,108 @@
+import { publicKeyToAddress } from 'viem/accounts';
+import { BotanaryApiError } from './errors.js';
+export function invalidResponse() {
+    const error = new BotanaryApiError('Botanary returned an invalid response. Nothing was signed.', 0);
+    error.code = 'invalid_response';
+    throw error;
+}
+export function record(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return invalidResponse();
+    return value;
+}
+export function hex(value, bytes) {
+    if (typeof value !== 'string' || !/^0x(?:[0-9a-fA-F]{2})*$/.test(value) || (bytes !== undefined && value.length !== 2 + 2 * bytes))
+        invalidResponse();
+}
+export function resourceId(value) {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(value) || /^(?:bsk|ags|dcs|dca|dcr)_/.test(value))
+        invalidResponse();
+}
+function uint(value) {
+    if (typeof value !== 'string' || !/^(0|[1-9][0-9]{0,77})$/.test(value) || BigInt(value) >= 2n ** 256n)
+        invalidResponse();
+}
+export function publicIdentity(value) {
+    const row = record(value);
+    hex(row.address, 20);
+    hex(row.publicKey, 65);
+    if (!row.publicKey.startsWith('0x04') || publicKeyToAddress(row.publicKey).toLowerCase() !== row.address.toLowerCase() ||
+        typeof row.fingerprint !== 'string' || !/^[A-Za-z0-9]{1,32}$/.test(row.fingerprint) ||
+        typeof row.backend !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(row.backend) ||
+        typeof row.createdAt !== 'string' || !Number.isFinite(Date.parse(row.createdAt)))
+        invalidResponse();
+    // Copy only public fields. A custom signer returning extra fields cannot leak them via identity().
+    return Object.freeze({ address: row.address, publicKey: row.publicKey, fingerprint: row.fingerprint,
+        backend: row.backend, createdAt: row.createdAt });
+}
+/** The public v0.7 contract permits decimal or hex integer quantities. Bytes remain hex-only. */
+export function userOpQuantity(value, bits = 256) {
+    if (typeof value !== 'string' || !/^(0|[1-9][0-9]{0,77}|0x[0-9a-fA-F]{1,64})$/.test(value))
+        return invalidResponse();
+    const result = BigInt(value);
+    if (result >= 2n ** BigInt(bits))
+        return invalidResponse();
+    return result;
+}
+export function unsignedUserOp(value) {
+    const row = record(value);
+    for (const name of ['sender', 'entryPoint'])
+        hex(row[name], 20);
+    for (const name of ['nonce', 'callGasLimit', 'verificationGasLimit', 'preVerificationGas', 'maxFeePerGas', 'maxPriorityFeePerGas'])
+        userOpQuantity(row[name]);
+    for (const name of ['callData', 'signature'])
+        hex(row[name]);
+    for (const name of ['paymasterVerificationGasLimit', 'paymasterPostOpGasLimit'])
+        if (row[name] != null)
+            userOpQuantity(row[name], 128);
+    if (!Number.isSafeInteger(row.chainId) || Number(row.chainId) <= 0)
+        invalidResponse();
+    for (const name of ['factory', 'paymaster'])
+        if (row[name] != null)
+            hex(row[name], 20);
+    for (const name of ['factoryData', 'paymasterData'])
+        if (row[name] != null)
+            hex(row[name]);
+    return value;
+}
+export function readyRequirement(value) {
+    const row = record(value);
+    hex(row.payload, 32);
+    hex(row.validator, 20);
+    if (!Number.isSafeInteger(row.index) || Number(row.index) < 0 || Number(row.index) >= 2 ** 32)
+        invalidResponse();
+    const auth = record(row.authorization);
+    hex(auth.from, 20);
+    hex(auth.to, 20);
+    hex(auth.nonce, 32);
+    uint(auth.value);
+    uint(auth.validAfter);
+    uint(auth.validBefore);
+    if (BigInt(auth.validBefore) <= BigInt(auth.validAfter))
+        invalidResponse();
+    return { payload: row.payload, validator: row.validator, index: Number(row.index), authorization: {
+            from: auth.from, to: auth.to, nonce: auth.nonce, value: auth.value, validAfter: auth.validAfter, validBefore: auth.validBefore,
+        } };
+}
+/** Bind a recovery response to the requested handle; never treat provider success as payment proof. */
+export function apiCallStatus(value, requirementId) {
+    const row = record(value);
+    if (row.requirementId !== requirementId || typeof row.simulated !== 'boolean')
+        invalidResponse();
+    const expected = { ready: ['not_submitted'], pending_approval: ['not_submitted'],
+        submitted: ['pending'], settled: ['settled'], declined: ['not_submitted', 'not_settled'] };
+    if (typeof row.status !== 'string' || !Object.hasOwn(expected, row.status) || !expected[row.status].includes(String(row.paymentStatus)))
+        invalidResponse();
+    if (row.providerStatus !== undefined && (!Number.isSafeInteger(row.providerStatus) || Number(row.providerStatus) < 100 || Number(row.providerStatus) > 599))
+        invalidResponse();
+    if (row.txHash !== undefined)
+        hex(row.txHash, 32);
+    if (row.status === 'settled')
+        hex(row.txHash, 32);
+    if (row.status === 'ready')
+        readyRequirement(row.ready);
+    else if (row.ready !== undefined)
+        invalidResponse();
+    return row;
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}

package/dist/views.d.ts

@@ -0,0 +1,182 @@
+import type { Hex } from 'viem';
+import type { components } from './generated/schema.js';
+type HexFields<T> = {
+    [K in keyof T]: K extends 'sender' | 'entryPoint' | 'callData' | 'signature' | 'factory' | 'factoryData' | 'paymaster' | 'paymasterData' ? Hex | Extract<T[K], null | undefined> : T[K];
+};
+export type UnsignedUserOp = HexFields<components['schemas']['UnsignedUserOp']>;
+/** An UNSIGNED userOp build response shape (`POST /delegations/{delegationId}/actions`, the ONLY build
+ *  lane whose op a session-key signature can actually validate - see `buildDelegatedAction`'s own doc
+ *  comment) - the UserOp wire fields are generated from the reviewed API contract. Compatibility views below
+ *  retain the historical MCP fields while the transport contract supplies the complete wire types. */
+export interface UserOpBuildResult {
+    intentType: string;
+    userOp: UnsignedUserOp;
+    userOpHash: Hex;
+    [key: string]: unknown;
+}
+/** One entry of `AgentSelf.grant.policySet.spentToDate` (backend's `SpendMeter`) - what tells a caller
+ *  how much of a budgeted token is left before it tries to spend more than a grant allows. */
+export interface SpendMeterView {
+    token: {
+        symbol: string;
+        chainId?: number | null;
+        address?: string | null;
+        assetRef?: string | null;
+    };
+    limit: number;
+    spent: number;
+    remaining: number;
+    expiresAt?: string | null;
+}
+/** The SWAP venue a grant pins, when it was granted swap authority at all (backend's
+ *  `PolicySet.swapVenue`). ABSENT - not null - on a transfer-only grant, which is exactly what makes it
+ *  answerable: the compiled Smart Sessions session is not readable back from a `permissionId`, so this
+ *  recorded fact is the only way either side can know whether the session carries an allowance action.
+ *  `maxAllowance` is DISPLAY units (the backend scales it by the token's own resolution), so it compares
+ *  directly against `propose_swap`'s `amountIn`. */
+export interface GrantSwapVenueView {
+    /** The one router this grant may approve AND call - the allowance entrypoint has one `(token, target)`. */
+    router: string;
+    /** The one token this grant may sell. */
+    token: {
+        symbol: string;
+        chainId?: number | null;
+        address?: string | null;
+    };
+    /** Ceiling on a SINGLE swap's allowance, in display units. Not a budget: the grant's own budget meters
+     *  separately, and both apply. */
+    maxAllowance: number;
+}
+/** The live grant `GET /agents/me` reports, when one exists - mirrors the backend's `Delegation` (only
+ *  the fields this package reads). */
+export interface AgentGrantView {
+    id: string;
+    permissionId: Hex;
+    status: string;
+    humanSummary: string;
+    chain: string;
+    chainId: number;
+    policySet: {
+        /** `token.assetRef` is stamped on at READ time by the backend's `withGrantAssetRefs`
+         *  (`grant-asset-refs.ts`) - CAIP-19, e.g. `eip155:8453/erc20:0x...` - and is what
+         *  `findBudgetMeter`/`checkSendBounds` match a resolved send against, never the symbol. `null`
+         *  means this build could not resolve an on-chain address for the token (honestly undecodable,
+         *  never guessed); absent (older backend) means "not reported". */
+        budgets: Array<{
+            token: {
+                symbol: string;
+                chainId?: number | null;
+                assetRef?: string | null;
+            };
+            amount: number;
+        }>;
+        perActionMax?: {
+            token: {
+                symbol: string;
+                chainId?: number | null;
+                assetRef?: string | null;
+            };
+            amount: number;
+        } | null;
+        recipientAllowlist?: Array<{
+            address: string;
+            name?: string | null;
+        }>;
+        expiresAt?: string | null;
+        /** Absent unless this grant was given swap authority - see `GrantSwapVenueView`. */
+        swapVenue?: GrantSwapVenueView | null;
+        [key: string]: unknown;
+    };
+    spentToDate: SpendMeterView[];
+    [key: string]: unknown;
+}
+/** `GET /agents/me`'s response - who this agent is, what account it is bound to, and its live grant if
+ *  any. `grant: null` is an honest, explicit answer (see agents.controller.ts's own doc comment), never
+ *  an error and never fabricated by this package. */
+export interface AgentSelf {
+    id: string;
+    name: string;
+    address: Hex;
+    fingerprint: string;
+    connectedAt: string;
+    accountId: string;
+    /** The bound account's own on-chain address - the one identifier the owner actually recognises, since
+     *  `accountId` is an opaque row id that appears nowhere in the Botanary app. Without it, an agent
+     *  paired to a DIFFERENT login than the one the owner has open reports itself connected and gives
+     *  them nothing to notice the mismatch with. Optional here because an older backend does not send it;
+     *  this package never fabricates one. */
+    accountAddress?: Hex | null;
+    grant: AgentGrantView | null;
+    /** Whether the grant's own chain has every setup module the account needs. Optional because an older
+     *  backend does not send it - absent means "not reported", which this package treats as "no evidence
+     *  of a problem" rather than inventing either answer. */
+    accountSetup?: {
+        ready: boolean;
+        missing: string[];
+        chainId: number;
+    } | null;
+}
+/** A submitted call, exactly the shape `POST /agents/requests`'s `calls` field and a money/swap build's
+ *  own callData/value/to already share. */
+export interface UnsignedCallView {
+    to: string;
+    data: string;
+    value: string;
+    chainId: number;
+}
+/** `POST /agents/requests`'s response - the raised request, including which bound was crossed and the
+ *  deadline, exactly as the backend reports them (never fabricated here). */
+export interface AgentRequestView {
+    id: string;
+    agentId: string;
+    accountId: string;
+    calls: UnsignedCallView[];
+    declineReason: string;
+    reason: string;
+    raisedAt: string;
+    expiresAt: string;
+    status: string;
+    [key: string]: unknown;
+}
+/** The exact EIP-3009 tuple this lane's `X402PaymentValidator` verifies, field order load-bearing - it
+ *  must match `IX402PaymentValidator.Authorization` in botanary-contracts exactly (reorder a field and
+ *  every signature stops verifying; see that interface's own doc comment). Decimal-string value fields,
+ *  mirroring the backend's own `X402Authorization` wire shape (`src/modules/x402/x402-authorization.ts`)
+ *  rather than a bigint: JSON has no integer wide enough for a uint256, and this package never imports
+ *  across the BE boundary to reuse that type directly (deploy-isolated - see the workspace AGENTS.md). */
+export interface X402AuthorizationView {
+    from: Hex;
+    to: Hex;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: Hex;
+    [key: string]: unknown;
+}
+/** `POST /apis/calls/requirements`'s `ready` branch (Task 13) - everything `callApi` needs to build the
+ *  Kernel ERC-1271 envelope. `validator` is the `X402PaymentValidator` address on THIS call's chain,
+ *  read from here and never hardcoded: deployment addresses are nonce-shifted between chains, so the
+ *  same address means something different on another chain. */
+export interface ApiCallRequirementsReady {
+    requirementId: string;
+    status: 'ready';
+    payload: Hex;
+    authorization: X402AuthorizationView;
+    index: number;
+    validator: Hex;
+    [key: string]: unknown;
+}
+/** `POST /apis/calls/requirements`'s `pending_approval` branch (Task 11's confirmation threshold) -
+ *  carries NONE of `payload`/`authorization`/`index`/`validator`, structurally, not merely empty: the
+ *  digest is deliberately withheld until the owner answers. `callApi` must never try to sign off this
+ *  shape - see its own handling below. */
+export interface ApiCallRequirementsPending {
+    requirementId: string;
+    status: 'pending_approval';
+    approvalId: string;
+    expiresAt: string;
+    [key: string]: unknown;
+}
+export type ApiCallRequirementsResponse = ApiCallRequirementsReady | ApiCallRequirementsPending;
+export {};
+//# sourceMappingURL=views.d.ts.map

package/dist/views.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../src/views.ts"],"names":[],"mappings":"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"}

package/dist/views.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=views.js.map

package/dist/views.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.js","sourceRoot":"","sources":["../src/views.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@botanary/agent",
+  "version": "0.1.0-alpha.1",
+  "description": "Botanary agent session and execution runtime with an injected signer",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@11.5.1",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/generated/schema.d.ts"
+    }
+  },
+  "scripts": {
+    "generate": "node scripts/generate.mjs",
+    "check:generated": "node scripts/generate.mjs --check",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "test": "vitest run",
+    "prepack": "pnpm check:generated && pnpm typecheck && pnpm build",
+    "test:packed": "node scripts/verify-packed.mjs"
+  },
+  "dependencies": {
+    "openapi-fetch": "0.17.0",
+    "viem": "2.54.6"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.15",
+    "openapi-typescript": "7.13.0",
+    "typescript": "5.9.3",
+    "vitest": "2.1.9",
+    "yaml": "2.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}