@botanary/agent 0.1.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/LICENSE +21 -0
  3. package/README.md +123 -0
  4. package/dist/errors.d.ts +49 -0
  5. package/dist/errors.d.ts.map +1 -0
  6. package/dist/errors.js +40 -0
  7. package/dist/errors.js.map +1 -0
  8. package/dist/exact-action.d.ts +48 -0
  9. package/dist/exact-action.d.ts.map +1 -0
  10. package/dist/exact-action.js +178 -0
  11. package/dist/exact-action.js.map +1 -0
  12. package/dist/fingerprint.d.ts +21 -0
  13. package/dist/fingerprint.d.ts.map +1 -0
  14. package/dist/fingerprint.js +47 -0
  15. package/dist/fingerprint.js.map +1 -0
  16. package/dist/generated/routes.d.ts +68 -0
  17. package/dist/generated/routes.d.ts.map +1 -0
  18. package/dist/generated/routes.js +92 -0
  19. package/dist/generated/routes.js.map +1 -0
  20. package/dist/generated/schema.d.ts +2903 -0
  21. package/dist/generated/schema.d.ts.map +1 -0
  22. package/dist/generated/schema.js +2 -0
  23. package/dist/generated/schema.js.map +1 -0
  24. package/dist/http-path.d.ts +92 -0
  25. package/dist/http-path.d.ts.map +1 -0
  26. package/dist/http-path.js +201 -0
  27. package/dist/http-path.js.map +1 -0
  28. package/dist/index.d.ts +11 -0
  29. package/dist/index.d.ts.map +1 -0
  30. package/dist/index.js +7 -0
  31. package/dist/index.js.map +1 -0
  32. package/dist/pairing-code.d.ts +41 -0
  33. package/dist/pairing-code.d.ts.map +1 -0
  34. package/dist/pairing-code.js +60 -0
  35. package/dist/pairing-code.js.map +1 -0
  36. package/dist/registration.d.ts +21 -0
  37. package/dist/registration.d.ts.map +1 -0
  38. package/dist/registration.js +62 -0
  39. package/dist/registration.js.map +1 -0
  40. package/dist/runtime.d.ts +203 -0
  41. package/dist/runtime.d.ts.map +1 -0
  42. package/dist/runtime.js +559 -0
  43. package/dist/runtime.js.map +1 -0
  44. package/dist/signer.d.ts +33 -0
  45. package/dist/signer.d.ts.map +1 -0
  46. package/dist/signer.js +13 -0
  47. package/dist/signer.js.map +1 -0
  48. package/dist/transport.d.ts +13 -0
  49. package/dist/transport.d.ts.map +1 -0
  50. package/dist/transport.js +135 -0
  51. package/dist/transport.js.map +1 -0
  52. package/dist/validation.d.ts +15 -0
  53. package/dist/validation.d.ts.map +1 -0
  54. package/dist/validation.js +108 -0
  55. package/dist/validation.js.map +1 -0
  56. package/dist/views.d.ts +182 -0
  57. package/dist/views.d.ts.map +1 -0
  58. package/dist/views.js +2 -0
  59. package/dist/views.js.map +1 -0
  60. package/package.json +50 -0
@@ -0,0 +1,62 @@
1
+ import { recoverMessageAddress } from 'viem';
2
+ import { BotanaryApiError } from './errors.js';
3
+ import { hex, invalidResponse, publicIdentity, resourceId } from './validation.js';
4
+ /** Registration proves possession of this agent key. It creates neither owner consent nor a grant. */
5
+ export async function registerAgent(signer, client, name) {
6
+ if (typeof name !== 'string' || name.trim().length < 1 || name.trim().length > 80)
7
+ throw new Error('Agent name must contain 1 to 80 characters.');
8
+ let identity;
9
+ try {
10
+ identity = publicIdentity(await signer.ensure());
11
+ }
12
+ catch {
13
+ throw signerFailure();
14
+ }
15
+ const context = await client.app.context();
16
+ resourceId(context.appId);
17
+ resourceId(context.keyId);
18
+ if (!['test', 'live'].includes(context.environment))
19
+ invalidResponse();
20
+ const publicKey = identity.publicKey.toLowerCase();
21
+ const address = identity.address.toLowerCase();
22
+ const challenge = await client.agents.challenge({ publicKey, name: name.trim() });
23
+ if (!challenge || challenge.appId !== context.appId || challenge.environment !== context.environment ||
24
+ challenge.publicKey !== publicKey || challenge.address !== address || !/^dach_[A-Za-z0-9_-]{43}$/.test(challenge.id) ||
25
+ typeof challenge.expiresAt !== 'string' || !Number.isFinite(Date.parse(challenge.expiresAt)) ||
26
+ Date.parse(challenge.expiresAt) <= Date.now() || Date.parse(challenge.expiresAt) > Date.now() + 360_000)
27
+ invalidResponse();
28
+ const message = [
29
+ 'Botanary agent registration', 'Purpose: register-agent-key', 'Audience: botanary:developer-platform:2026-09-07',
30
+ `Application: ${context.appId}`, `Environment: ${context.environment}`, `API key: ${context.keyId}`,
31
+ `Public key: ${publicKey}`, `Address: ${address}`, `Nonce: ${challenge.id}`, `Expires: ${challenge.expiresAt}`,
32
+ 'This proof does not authorize an account connection or an on-chain grant.',
33
+ ].join('\n');
34
+ if (challenge.message !== message)
35
+ invalidResponse();
36
+ let signature;
37
+ try {
38
+ signature = await signer.sign(message);
39
+ hex(signature, 65);
40
+ if ((await recoverMessageAddress({ message, signature })).toLowerCase() !== address)
41
+ throw signerFailure();
42
+ }
43
+ catch {
44
+ throw signerFailure();
45
+ }
46
+ const registration = await client.agents.complete({ challengeId: challenge.id, signature });
47
+ if (!registration || registration.appId !== context.appId || registration.environment !== context.environment ||
48
+ registration.publicKey !== publicKey || registration.address !== address || registration.grantStatus !== 'unknown' ||
49
+ !['awaiting_connection', 'active', 'disabled', 'app_disabled', 'key_revoked', 'connection_revoked', 'unavailable'].includes(registration.apiAccess) ||
50
+ (registration.apiAccess === 'active' && registration.connectionId === null) ||
51
+ (registration.apiAccess === 'awaiting_connection' && registration.connectionId !== null))
52
+ invalidResponse();
53
+ if (registration.connectionId !== null)
54
+ resourceId(registration.connectionId);
55
+ return registration;
56
+ }
57
+ function signerFailure() {
58
+ const error = new BotanaryApiError('The agent signer could not complete registration.', 0);
59
+ error.code = 'signer_error';
60
+ return error;
61
+ }
62
+ //# sourceMappingURL=registration.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"registration.js","sourceRoot":"","sources":["../src/registration.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,203 @@
1
+ import { type ExactAgentAction, type AgentActionBinding, type AgentSwapBinding, type PreparedAgentAction } from './exact-action.js';
2
+ import { type Hex } from 'viem';
3
+ import { type PairingCode } from './pairing-code.js';
4
+ import { type AgentTransport } from './transport.js';
5
+ import type { AgentIdentity, AgentSigner } from './signer.js';
6
+ import type { AgentSelf, AgentRequestView, UnsignedCallView, UserOpBuildResult, UnsignedUserOp } from './views.js';
7
+ /**
8
+ * Poll `get` until the op reports a terminal status or `budgetMs` is spent, then return whatever the
9
+ * backend last said - VERBATIM. A budget lapse returns the real `pending` answer; this helper never
10
+ * invents a status, and never blocks forever.
11
+ *
12
+ * Pure and injectable (clock + sleep) so its behaviour is testable without timers or a network.
13
+ */
14
+ export declare function awaitTerminalWith(get: (opId: string) => Promise<Record<string, unknown>>, opId: string, budgetMs: number, now: () => number, sleep: (ms: number) => Promise<void>): Promise<Record<string, unknown>>;
15
+ /** Default API origin. The shared runtime reads no environment variables; its host supplies overrides. */
16
+ export declare const DEFAULT_API_BASE_URL = "https://api.app.botanary.xyz";
17
+ /** Per-instance agent identity and sessions. The signer owns all private-key storage. */
18
+ export declare class AgentRuntime {
19
+ #private;
20
+ constructor(signer: AgentSigner, options?: {
21
+ baseUrl?: string;
22
+ fetch?: typeof fetch;
23
+ transport?: AgentTransport;
24
+ provenance?: {
25
+ client?: string;
26
+ profile?: string;
27
+ };
28
+ });
29
+ get apiBaseUrl(): string;
30
+ protected get identityMaterialized(): boolean;
31
+ protected setProvenance(value: {
32
+ client?: string;
33
+ profile?: string;
34
+ }): void;
35
+ protected replaceSigner(signer: AgentSigner): void;
36
+ /** The agent's public identity, creating it on first call if none exists yet. Cached for the life of
37
+ * this runtime (the address/fingerprint cannot change without a forget(), which calls reset()). */
38
+ identity(): Promise<AgentIdentity>;
39
+ pairingCode(): Promise<PairingCode>;
40
+ regeneratePairingCode(): Promise<PairingCode>;
41
+ pair(): Promise<PairingCode>;
42
+ /** Mint a FRESH session unconditionally (bypasses the cache - this is what re-minting after expiry or
43
+ * a 401 calls). Also (re)populates the cache, so an ordinary tool call right after this one reuses it
44
+ * via `ensureSession()` instead of minting again. */
45
+ mintSession(): Promise<string>;
46
+ /** The token every read/build/spend call below actually uses: the cached session if it is still safe
47
+ * to reuse, otherwise a freshly minted one. This is what makes "every tool call does not re-mint" true
48
+ * without any caller having to think about session lifetime. */
49
+ ensureSession(): Promise<string>;
50
+ /** `GET /agents/me` - this agent's own identity, its bound account, and its live grant if any (or an
51
+ * honest `grant: null`). Re-mints the session once and retries on a 401 (a token that expired between
52
+ * `ensureSession()`'s check and the request landing, or one the backend otherwise no longer honors). */
53
+ me(): Promise<AgentSelf>;
54
+ /** `GET /balance` - the account address and its token/holdings breakdown, exactly as the backend
55
+ * reports it. */
56
+ getBalance(): Promise<Record<string, unknown>>;
57
+ /** `GET /agents/requests` - every approval request this agent has filed, with the owner's verdict
58
+ * (`status`, `declineReason`) and deadline. The read half of `request_approval`: without it an agent
59
+ * files a request it can never learn the outcome of. */
60
+ listRequests(): Promise<unknown>;
61
+ /** `GET /chains` - every chain this build serves, each with the `chainTier` that decides what it can
62
+ * do (`watch` read-only, `basic` no AgentGuard, `botanary` full authority). */
63
+ listChains(): Promise<unknown>;
64
+ /** `GET /gas/methods` - only the gas methods actually AVAILABLE on the given chain (the backend
65
+ * filters unavailable/sponsored ones out itself). Every parameter is optional and passed through
66
+ * untouched; `key` is the Stellar/Solana key-keyed lane, `chainId` the EVM numeric one. */
67
+ getGasMethods(params: {
68
+ chainId?: number;
69
+ accountId?: string;
70
+ key?: string;
71
+ }): Promise<unknown>;
72
+ /** `GET /account` - SINGULAR: the one account this agent's session resolves to, optionally for a
73
+ * specific chain. Carries `address` and `deploymentStatus`. */
74
+ getAccount(params: {
75
+ chainId?: number;
76
+ }): Promise<unknown>;
77
+ /** Build and verify a bound action. Submission is explicit and attempted at most once per handle. */
78
+ prepareExactAction(input: ExactAgentAction, binding: AgentActionBinding | AgentSwapBinding): Promise<PreparedAgentAction>;
79
+ /**
80
+ * `POST /delegations/{delegationId}/actions` - an UNSIGNED delegated-action op, built in the
81
+ * delegation's OWN Smart Sessions nonce lane with fixed native gas (the session validator cannot
82
+ * gas-estimate a stub signature). This is the ONLY build lane a session-key signature can validate:
83
+ * `POST /money/send/build` (this package's earlier, WRONG choice) builds in the Kernel account's ROOT
84
+ * nonce lane for the OWNER's key - an op built there, then signed with this agent's session key and
85
+ * wrapped in `spendUnderGrant`'s USE envelope, would route validation to the root ECDSA validator,
86
+ * which cannot parse a `(bytes1, bytes32, bytes)` envelope as a 65-byte ECDSA signature. `delegationId`
87
+ * is this agent's OWN grant id (`GET /agents/me`'s `grant.id` - never invented, never another agent's:
88
+ * the backend refuses that with a named 403, see the workspace's delegation.controller.ts). `amount` is
89
+ * DISPLAY units (e.g. `12.5` for 12.5 USDC), matching `DelegatedActionInput.amount` - never wei.
90
+ * `token`, when given, disambiguates which of the delegation's budgeted tokens to move - a contract
91
+ * address or CAIP-19 asset ref (Task A11), required whenever the grant budgets more than one
92
+ * stablecoin. Omitted, the backend defaults to it ONLY when exactly one token is budgeted; a
93
+ * multi-budget grant given neither refuses rather than silently picking the first (`propose_payment`
94
+ * always resolves and passes one - see `agent-actions.ts`).
95
+ */
96
+ buildDelegatedAction(params: {
97
+ delegationId: string;
98
+ recipient: string;
99
+ amount: number;
100
+ token?: string;
101
+ }): Promise<UserOpBuildResult>;
102
+ /**
103
+ * `POST /delegations/{delegationId}/actions` with `action: 'swap'` - the SAME endpoint, the same session
104
+ * nonce lane and the same fixed gas as `buildDelegatedAction` above; only the body's shape differs. The
105
+ * backend discriminates on `action` explicitly and NEVER infers it from the presence of `tokenIn`, so a
106
+ * transfer body with a typo stays a 422 on the wrong field rather than silently becoming a swap.
107
+ *
108
+ * Symbols, not addresses: unlike `buildDelegatedAction`'s `token` (Task A11), this shape was NOT widened
109
+ * to accept an address or asset ref - the backend re-resolves both legs from ITS OWN per-chain manifest,
110
+ * which is the same resolution `buildGrant` used when it compiled the venue's `EQ` rule, so the two
111
+ * cannot disagree. `propose_swap` (`agent-actions.ts`) still takes an address/asset ref from ITS OWN
112
+ * caller (`assetIn`/`assetOut`) and resolves each to a verified symbol before calling this - so the
113
+ * package-external argument names moved even though this wire shape did not. `amountIn` is DISPLAY
114
+ * units (e.g. `25` for 25 USDC), matching `amount` on the transfer shape.
115
+ *
116
+ * The op this produces is ONE call into `GrantExecutor.executeUnderGrantWithAllowance` - approve, route,
117
+ * zero, assert no residual - which the grant's session authorises only when the grant named a
118
+ * `swapVenue`. A grant without one has no such action at all and the backend declines
119
+ * `grant_swap_not_authorised` rather than handing back an op Smart Sessions would refuse in validation.
120
+ */
121
+ buildDelegatedSwap(params: {
122
+ delegationId: string;
123
+ tokenIn: string;
124
+ tokenOut: string;
125
+ amountIn: number;
126
+ maxSlippageBps?: number;
127
+ }): Promise<UserOpBuildResult>;
128
+ /** `POST /agents/requests` - the "ask" half of the design (Flow 7d step 5): raise a request naming the
129
+ * calls that were declined and why, returning which bound was crossed and the deadline exactly as the
130
+ * backend computed them. */
131
+ raiseRequest(calls: UnsignedCallView[], reason: string): Promise<AgentRequestView>;
132
+ /**
133
+ * Sign a built op as the grant's session key and relay it. The USE envelope is EXACTLY the three lines
134
+ * `botanary-fe/src/lib/wallet/signing.ts:49` already uses - `SmartSessionMode.USE` is `0x00`, and the
135
+ * packing is `(bytes1, bytes32, bytes)`. Reproduced rather than re-derived: a second encoding of the same
136
+ * envelope is a second thing to get byte-exact, and only one of them would be tested.
137
+ *
138
+ * `intentType` is the SAME value the build response itself reported (`UserOpBuildResult.intentType`,
139
+ * `'delegated_action'` for `buildDelegatedAction`'s builds) - never assumed or hardcoded here, so the
140
+ * relay always describes what was actually built, which is what `OrchestratorService.submit` uses to
141
+ * label the audit trail entry.
142
+ *
143
+ * Returns the backend's OWN relay response (status/txHash/error, whatever `POST /userops` actually
144
+ * said) rather than nothing - a caller (`propose_payment`) reporting success has to report what the
145
+ * backend reported, never a string this package made up.
146
+ */
147
+ spendUnderGrant(userOp: UnsignedUserOp, userOpHash: Hex, permissionId: Hex, token: string, intentType: string): Promise<Record<string, unknown>>;
148
+ /** `GET /userops/{opId}` - the receipt for an op THIS agent relayed. Reachable only because that route
149
+ * now carries `@AgentAllowed()`; before that it 403'd an `ags_` token before the handler ran. */
150
+ getUserOp(opId: string): Promise<Record<string, unknown>>;
151
+ /** Read the original agent submission without building or signing another operation. */
152
+ getUserOpByHash(chainId: number, hash: Hex): Promise<Record<string, unknown>>;
153
+ /** Follow an op to a terminal status, bounded. See `awaitTerminalWith`. */
154
+ awaitTerminal(opId: string, budgetMs: number): Promise<Record<string, unknown>>;
155
+ /** `GET /apis/providers` - the ranked, searchable catalog of API providers on a chain, with each
156
+ * provider's endpoint count, verified count, minimum and maximum price in atomic units (nullable).
157
+ * Does NOT call an endpoint or spend anything. Returns
158
+ * `{ providers, total, hidden, reasons, reasonsTruncated }`.
159
+ *
160
+ * The route is `/apis/providers`, not the `/apis/list` this file used to call: the backend's
161
+ * api-catalog controller serves `providers` and `providers/:providerId` and has no `list` route at
162
+ * all, so the old path 404s. botanary-mcp@0.6.1 was published with this corrected route but the
163
+ * change was never committed, which is how the repository came to describe a dead endpoint while
164
+ * the published package worked. */
165
+ listApis(chainId: number): Promise<unknown>;
166
+ /** `GET /apis/providers/{providerId}` - one provider with a page of its endpoints, each with its
167
+ * live price as measured or declared (nullable), and whether it is payable on this chain. Returns
168
+ * the `ApiProviderDetail` shape, with an `endpoints` array. */
169
+ getApiProvider(providerId: string, chainId?: number): Promise<unknown>;
170
+ /**
171
+ * Call a paid third-party API endpoint and pay for it from the owner's wallet, within the budget the
172
+ * owner committed on chain. Build -> sign -> relay, exactly like every other spending lane here.
173
+ *
174
+ * This used to `POST /v1/apis/calls`, a route that has never existed - the contract has
175
+ * `/apis/calls/requirements` and `/apis/calls/relay`, and there is no composite. There could not be
176
+ * one: a single endpoint would have to sign, and the backend holds no key. So the two halves are both
177
+ * real calls, with the signature produced HERE, from this agent's own key.
178
+ *
179
+ * `payload` is a 32-byte EIP-712 digest over an EIP-3009 `TransferWithAuthorization`. Signing it
180
+ * authorises exactly one transfer, of a value and to a recipient the digest already fixes; USDC
181
+ * verifies the result via ERC-1271 against the owner's account, which routes to
182
+ * `X402PaymentValidator` and is refused unless this agent key is inside a live budget.
183
+ */
184
+ callApi(params: {
185
+ chainId: number;
186
+ providerId: string;
187
+ endpointId: string;
188
+ url: string;
189
+ /** Raw POST body, forwarded byte for byte. The price is quoted for THIS body and the paid request
190
+ * replays exactly it, so a caller cannot get a cheap quote and then send something expensive. */
191
+ body?: string;
192
+ }): Promise<Record<string, unknown>>;
193
+ /** Read durable submission status first. A submitted payment is never signed or forwarded again. */
194
+ resumeApi(requirementId: string, budgetMs?: number): Promise<Record<string, unknown>>;
195
+ /** `GET /apis/budget` - remaining authorizations, per-call maximum, expiry and epoch for this agent
196
+ * on a chain. Does NOT tell you which endpoints this agent may reach. */
197
+ getApiBudget(chainId: number): Promise<unknown>;
198
+ /** Drops cached identity/pairing/session state. Call after `store.forget()` so the next call re-derives
199
+ * from storage (and, in the ordinary case, creates a brand new identity) instead of continuing to serve
200
+ * an in-memory identity - or a session minted for it - whose key is now gone. */
201
+ reset(): void;
202
+ }
203
+ //# sourceMappingURL=runtime.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}