@botanary/agent 0.1.0-alpha.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0-alpha.1
+
+- Recover durable API payment status without signing or forwarding an existing submission again.
+- Distinguish finalized payment evidence from provider HTTP success and retain uncertain outcomes.
+
+- Extract agent signing, pairing, sessions, delegated execution, API payments and waits from MCP.
+- Inject signer storage and preserve desktop profile and owner-session behavior in MCP.
+- Generate agent wire types and transport routes from the reviewed canonical API contract.
+- Validate signing inputs, registration context and session responses at runtime.
+- Coalesce session refreshes and retain existing reconciliation handles after failures.
+- Verify standalone and tool consumers using packed artifacts outside the workspace.
+
+- Add exact transfer/swap preparation, transaction and hash verification, explicit native gas ceilings,
+  one-attempt submission handles and agent-scoped receipt lookup by original hash.
+- Support owner-approved registration bindings and proof-based app-credential rotation without
+  creating or widening a spending grant.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Botanary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @botanary/agent
+
+Alpha version 0.1.0-alpha.1, canonical API contract 2026-09-07. MIT licensed. Node 22 or later.
+This package has not been verified against a deployed developer platform or a settled testnet transaction.
+
+The runtime is extracted from `botanary-mcp`. MCP keeps desktop keychain adapters, profile selection,
+owner sessions and approval handles. The CLI consumes that desktop adapter through MCP. The shared
+package has no dependency on desktop storage, the Botanary backend or frontend source.
+
+```ts
+// Node server only. The caller supplies an agent signer whose private key stays in its own storage.
+import { AgentRuntime, registerAgent, type AgentSigner } from '@botanary/agent';
+import { createBotanary } from '@botanary/sdk';
+
+export async function registerAndRead(signer: AgentSigner) {
+  const app = createBotanary({ apiKey: process.env.BOTANARY_SECRET_KEY! });
+  const registration = await registerAgent(signer, app, 'Research agent');
+  return { id: registration.id, access: registration.apiAccess, grant: registration.grantStatus };
+}
+
+export async function readConnectedAgent(signer: AgentSigner) {
+  const agent = new AgentRuntime(signer);
+  return agent.me();
+}
+```
+
+Registration requires `app:read` and `agents:write` on the app key. It verifies an EIP-191 challenge
+bound to the application, environment, key ID, agent public key, one-use nonce and expiry. It creates
+neither an account connection nor an on-chain grant. Pass the returned registration ID to
+`app.connections.begin({ agentRegistrationId: registration.id, redirectUri, scopes })`, including
+`accounts:read` and `agents:read` in the requested scopes. That app key also needs `connections:write`
+and every requested scope. The owner reviews the public key and explicitly checks the agent API
+option for one account. `me()` then describes that exact binding; registration alone cannot make it
+succeed. The owner still signs any spending grant separately.
+
+For app-key rotation, repeat `registerAgent` with an active same-app/environment key carrying every
+existing consent scope. This proves possession again, preserves the customer connection and
+invalidates old agent sessions. Revoked owner consent requires a new owner approval. Disabled
+registrations cannot be revived through registration proof.
+
+`AgentSigner` supplies `ensure()` with public metadata, `sign(message)` for EIP-191 registration,
+and `signHash(hash)` for raw session and execution digests. `createViemAgentSigner(account)` adapts
+an existing viem-compatible account; it does not load, generate, export or back up a key. Each customer
+connection needs a distinct identity. Independent runtime instances have independent cached sessions.
+
+Session creation coalesces concurrent calls, validates nonce and expiry, and refreshes rejected reads
+once. Mutations are not automatically retried. The default transport uses generated agent routes and
+openapi-fetch, refuses owner routes and app credentials, forbids redirects and cookies, and bounds
+response bodies and request time. The injected transport seam is for trusted host adapters such as MCP.
+
+`callApi` preserves the provider/endpoint requirements, signature and relay protocol. A pending
+approval includes its `requirementId`; `resumeApi(requirementId)` reads durable payment status before
+continuing approval, without making another requirements request. A failed relay carries its original requirement ID. Do not treat an
+ambiguous relay failure as permission to create a new purchase. The owner must complete paid-API setup
+first; per-agent off-chain mandate checks and the on-chain payment authorization remain distinct.
+
+`status: 'submitted'` with `paymentStatus: 'pending'` retains the same requirement while finalized
+chain evidence is unavailable. Resume it to read progress; the SDK never signs or forwards an already
+submitted payment again. `status: 'settled'` proves payment, while `providerStatus` separately records
+whether the provider served the request. A provider can fail after payment. Check both fields and the
+explicit `simulated` marker before presenting an outcome.
+
+`spendUnderGrant` validates the v0.7 UserOp shape, signs once and preserves its hash on relay errors.
+`awaitTerminal` returns the actual last reported state, including a pending state when its budget ends.
+Submission is not confirmation. Existing low-level `buildDelegatedAction` and `buildDelegatedSwap`
+methods retain the legacy display-number wire inputs for CLI/MCP compatibility. New integrations use
+`prepareExactAction` below. Customer binding and real testnet settlement proof remain release work.
+No mainnet grant capability is added here.
+
+## Exact execution
+
+An already connected agent with an owner-signed grant can prepare an action. Obtain the delegation ID,
+permission ID and pinned executor address from that approved grant and its network deployment. The
+app key is never an execution credential. Amounts and the maximum native gas cost are integer strings.
+
+```ts
+import { AgentRuntime, type AgentSigner, type AgentActionBinding } from '@botanary/agent';
+
+export async function sendUnderApprovedGrant(signer: AgentSigner, binding: AgentActionBinding) {
+  const runtime = new AgentRuntime(signer);
+  const prepared = await runtime.prepareExactAction({
+    accountId: 'your-connected-account-id',
+    accountAddress: '0x1111111111111111111111111111111111111111',
+    chainId: 84532,
+    action: 'transfer',
+    tokenAddress: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+    recipient: '0x2222222222222222222222222222222222222222',
+    amount: '1000000',
+  }, binding);
+  // Persist this hash with the application's logical operation before submitting.
+  const hash = prepared.userOpHash;
+  const receipt = await prepared.submit();
+  return { hash, receipt };
+}
+```
+
+Replace the example account and recipient with the owner-approved values. Preparation verifies the
+account, chain, permission, executor, exact calldata, Smart Sessions nonce lane, native gas ceiling and
+v0.7 EntryPoint hash. It refuses failed simulations, unexpected factories and paymasters. The on-chain
+grant remains the authority boundary; advisory simulation is not evidence of settlement.
+
+`submit()` signs and sends at most once for a prepared handle, including concurrent calls and failures.
+It never builds a replacement automatically. Persist the hash before submission. After a timeout use
+`prepared.reconcile()` or, after restarting the client, `runtime.getUserOpByHash(chainId, hash)`.
+A 404 means no submission is recorded; it does not prove the network rejected it. Keep the outcome
+unknown and reconcile before offering another spend. The prepared handle is process-local; durable
+application idempotency across process restarts is a separate platform delivery requirement.
+
+For a swap, use `action: 'swap'`, `tokenOutAddress`, integer `amount`, and optional `maxSlippageBps`.
+Pass an `AgentSwapBinding` that also pins `routerAddress` and integer `minAmountOut`. The default
+verifier decodes `swapExactIn(tokenIn, tokenOut, amountIn, minOut, to)` and checks both assets, input,
+minimum receive and receiving account. For another reviewed router ABI, supply `verifyRoute(facts)`
+and return true only after decoding and checking every supplied fact. Unknown router calldata is
+refused without that verifier. The outer grant call still pins the router, exact allowance and zero
+native value. A token address or slippage label in response metadata alone cannot authorize a swap.
+
+API access disablement and on-chain permission revocation are separate. Disabling a registration does
+not revoke a previously signed grant. Never interpret `grantStatus: unknown` as revoked authority.
+
+From this package directory: `pnpm install --frozen-lockfile`, `pnpm check:generated`, `pnpm typecheck`,
+`pnpm test`, and `pnpm test:packed`. Install the independent SDK package before the packed check.
+The optional `BOTANARY_VERIFY_TOOLS=1 pnpm test:packed` also packs MCP and CLI and drives a CLI agent
+read through the extracted runtime against a loopback HTTP fixture. Install those packages first.

package/dist/errors.d.ts

@@ -0,0 +1,49 @@
+/** Thrown for any non-2xx response, carrying the HTTP status alongside the SERVER's own message (never a
+ *  generic one - whoever built this agent needs the reason, §6-40 one layer up from the chain). The
+ *  status is what lets `AgentRuntime` tell "this session token is stale, re-mint and retry" (401) apart
+ *  from every other failure, which it should surface as-is. */
+export declare class BotanaryApiError extends Error {
+    readonly status: number;
+    /**
+     * The backend's own `error.details` blob, carried through rather than flattened into the message.
+     * Some refusals are ACTIONABLE and say so in structured fields - `missingModule` names a setup module
+     * the account lacks - and a tool that can only read prose has to pattern-match on wording to notice.
+     * Keeping the object means a handler keys off a field the backend guarantees instead of a sentence it
+     * is free to reword. Null whenever the response carried none.
+     */
+    readonly details: Record<string, unknown> | null;
+    /**
+     * The `Retry-After` header's value in SECONDS, when the server sent one (429/503 carry it). Null
+     * otherwise. Kept as a first-class field because a caller that wants to survive a rate limit -
+     * `wallet/login.ts`'s poll loop is the one that must - cannot see response headers otherwise, and
+     * guessing a backoff when the server told you the exact number is how a retry storm starts.
+     * Only the numeric (delta-seconds) form is parsed; the HTTP-date form yields null, and the caller
+     * falls back to its own backoff rather than mis-parsing a date as a duration.
+     */
+    readonly retryAfterSeconds: number | null;
+    requestId?: string;
+    code?: string;
+    operationId?: string;
+    userOpHash?: string;
+    requirementId?: string;
+    ambiguous: boolean;
+    constructor(message: string, status: number, 
+    /**
+     * The backend's own `error.details` blob, carried through rather than flattened into the message.
+     * Some refusals are ACTIONABLE and say so in structured fields - `missingModule` names a setup module
+     * the account lacks - and a tool that can only read prose has to pattern-match on wording to notice.
+     * Keeping the object means a handler keys off a field the backend guarantees instead of a sentence it
+     * is free to reword. Null whenever the response carried none.
+     */
+    details?: Record<string, unknown> | null, 
+    /**
+     * The `Retry-After` header's value in SECONDS, when the server sent one (429/503 carry it). Null
+     * otherwise. Kept as a first-class field because a caller that wants to survive a rate limit -
+     * `wallet/login.ts`'s poll loop is the one that must - cannot see response headers otherwise, and
+     * guessing a backoff when the server told you the exact number is how a retry storm starts.
+     * Only the numeric (delta-seconds) form is parsed; the HTTP-date form yields null, and the caller
+     * falls back to its own backoff rather than mis-parsing a date as a duration.
+     */
+    retryAfterSeconds?: number | null);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;+DAG+D;AAC/D,qBAAa,gBAAiB,SAAQ,KAAK;IASvC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAChD;;;;;;;OAOG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI;IAzB3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,UAAS;gBAEhB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM;IACvB;;;;;;OAMG;IACM,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAW;IACvD;;;;;;;OAOG;IACM,iBAAiB,GAAE,MAAM,GAAG,IAAW;CAKnD"}

package/dist/errors.js

@@ -0,0 +1,40 @@
+/** Thrown for any non-2xx response, carrying the HTTP status alongside the SERVER's own message (never a
+ *  generic one - whoever built this agent needs the reason, §6-40 one layer up from the chain). The
+ *  status is what lets `AgentRuntime` tell "this session token is stale, re-mint and retry" (401) apart
+ *  from every other failure, which it should surface as-is. */
+export class BotanaryApiError extends Error {
+    status;
+    details;
+    retryAfterSeconds;
+    requestId;
+    code;
+    operationId;
+    userOpHash;
+    requirementId;
+    ambiguous = false;
+    constructor(message, status, 
+    /**
+     * The backend's own `error.details` blob, carried through rather than flattened into the message.
+     * Some refusals are ACTIONABLE and say so in structured fields - `missingModule` names a setup module
+     * the account lacks - and a tool that can only read prose has to pattern-match on wording to notice.
+     * Keeping the object means a handler keys off a field the backend guarantees instead of a sentence it
+     * is free to reword. Null whenever the response carried none.
+     */
+    details = null, 
+    /**
+     * The `Retry-After` header's value in SECONDS, when the server sent one (429/503 carry it). Null
+     * otherwise. Kept as a first-class field because a caller that wants to survive a rate limit -
+     * `wallet/login.ts`'s poll loop is the one that must - cannot see response headers otherwise, and
+     * guessing a backoff when the server told you the exact number is how a retry storm starts.
+     * Only the numeric (delta-seconds) form is parsed; the HTTP-date form yields null, and the caller
+     * falls back to its own backoff rather than mis-parsing a date as a duration.
+     */
+    retryAfterSeconds = null) {
+        super(message);
+        this.status = status;
+        this.details = details;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = 'BotanaryApiError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;+DAG+D;AAC/D,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAS9B;IAQA;IASA;IAzBX,SAAS,CAAU;IACnB,IAAI,CAAU;IACd,WAAW,CAAU;IACrB,UAAU,CAAU;IACpB,aAAa,CAAU;IACvB,SAAS,GAAG,KAAK,CAAC;IAClB,YACE,OAAe,EACN,MAAc;IACvB;;;;;;OAMG;IACM,UAA0C,IAAI;IACvD;;;;;;;OAOG;IACM,oBAAmC,IAAI;QAEhD,KAAK,CAAC,OAAO,CAAC,CAAC;QAnBN,WAAM,GAAN,MAAM,CAAQ;QAQd,YAAO,GAAP,OAAO,CAAuC;QAS9C,sBAAiB,GAAjB,iBAAiB,CAAsB;QAGhD,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}

package/dist/exact-action.d.ts

@@ -0,0 +1,48 @@
+import { type Hex } from 'viem';
+import type { components } from './generated/schema.js';
+import type { UnsignedUserOp } from './views.js';
+export type ExactAgentAction = components['schemas']['ExactDelegatedActionInput'];
+export type ExactAgentExecution = components['schemas']['ExactDelegatedExecution'];
+export interface AgentActionBinding {
+    delegationId: string;
+    permissionId: Hex;
+    executorAddress: Hex;
+    /** Maximum native gas cost for this operation, in wei. */
+    maxGasCostWei: string;
+}
+export interface SwapRouteFacts {
+    readonly chainId: number;
+    readonly accountAddress: Hex;
+    readonly routerAddress: Hex;
+    readonly tokenAddress: Hex;
+    readonly tokenOutAddress: Hex;
+    readonly amount: string;
+    readonly minAmountOut: string;
+    readonly callData: Hex;
+}
+export interface AgentSwapBinding extends AgentActionBinding {
+    routerAddress: Hex;
+    minAmountOut: string;
+    /** For a reviewed router ABI other than swapExactIn. Must verify all supplied facts. */
+    verifyRoute?: (facts: Readonly<SwapRouteFacts>) => boolean | Promise<boolean>;
+}
+export interface PreparedAgentAction {
+    readonly userOpHash: Hex;
+    readonly execution: Readonly<ExactAgentExecution>;
+    /** One attempt per prepared action, including concurrent calls and transport failures. */
+    submit(): Promise<Record<string, unknown>>;
+    /** Read by the original hash. A 404 is still an unknown network outcome. */
+    reconcile(): Promise<Record<string, unknown>>;
+}
+/** Copy and validate before awaiting transport, so caller mutations cannot change the signed intent. */
+export declare function exactActionInput(value: ExactAgentAction): ExactAgentAction;
+export declare function actionBinding(value: AgentActionBinding | AgentSwapBinding, action: ExactAgentAction): AgentActionBinding | AgentSwapBinding;
+/** Validate the actual call and recompute its chain-bound v0.7 hash before handing it to a signer. */
+export declare function validateExactAction(value: unknown, input: ExactAgentAction, binding: AgentActionBinding | AgentSwapBinding): Promise<{
+    userOp: UnsignedUserOp;
+    userOpHash: Hex;
+    execution: Readonly<ExactAgentExecution>;
+}>;
+/** Receipt validation happens after submission, so failure must retain the reconciliation handle. */
+export declare function exactActionReceipt(value: unknown, hash: Hex): Record<string, unknown>;
+//# sourceMappingURL=exact-action.d.ts.map

package/dist/exact-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact-action.d.ts","sourceRoot":"","sources":["../src/exact-action.ts"],"names":[],"mappings":"AACA,OAAO,EAAqG,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AAGnI,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,2BAA2B,CAAC,CAAC;AAClF,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,yBAAyB,CAAC,CAAC;AACnF,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,GAAG,CAAC;IAClB,eAAe,EAAE,GAAG,CAAC;IACrB,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAC;CACvB;AACD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,GAAG,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,GAAG,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC;CACxB;AACD,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB;IAC1D,aAAa,EAAE,GAAG,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,cAAc,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/E;AACD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IAClD,0FAA0F;IAC1F,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3C,4EAA4E;IAC5E,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC/C;AAkBD,wGAAwG;AACxG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,gBAAgB,CAkB1E;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,gBAAgB,EAAE,MAAM,EAAE,gBAAgB,GAAG,kBAAkB,GAAG,gBAAgB,CAU3I;AAED,sGAAsG;AACtG,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,kBAAkB,GAAG,gBAAgB,GAAG,OAAO,CAAC;IAC1I,MAAM,EAAE,cAAc,CAAC;IAAC,UAAU,EAAE,GAAG,CAAC;IAAC,SAAS,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAC;CACnF,CAAC,CA0ED;AAED,qGAAqG;AACrG,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYrF"}

package/dist/exact-action.js

@@ -0,0 +1,178 @@
+import { BotanaryApiError } from './errors.js';
+import { encodeFunctionData, encodePacked, decodeFunctionData, parseAbi, getAddress, zeroAddress, zeroHash } from 'viem';
+import { entryPoint07Address, getUserOperationHash } from 'viem/account-abstraction';
+import { hex, invalidResponse, record, resourceId, unsignedUserOp, userOpQuantity } from './validation.js';
+const kernelAbi = parseAbi(['function execute(bytes32 mode, bytes executionCalldata) payable']);
+const grantAbi = parseAbi([
+    'function executeUnderGrant(bytes32 permissionId, address target, uint256 value, bytes callData)',
+    'function executeUnderGrantWithAllowance(bytes32 permissionId, address target, uint256 value, address token, uint256 allowance, bytes callData)',
+]);
+const transferAbi = parseAbi(['function transfer(address to, uint256 amount) returns (bool)']);
+const swapAbi = parseAbi(['function swapExactIn(address tokenIn, address tokenOut, uint256 amountIn, uint256 minOut, address to) returns (uint256 amountOut)']);
+const sessionKey = BigInt('0x000100000000008bdaba73cd9815d79069c247eb4bda0000');
+function same(left, right) { return typeof left === 'string' && left.toLowerCase() === right.toLowerCase(); }
+function integer(value, positive = true) {
+    if (typeof value !== 'string' || !/^(0|[1-9][0-9]{0,77})$/.test(value))
+        return invalidResponse();
+    const result = BigInt(value);
+    if (result >= 2n ** 256n || (positive && result === 0n))
+        return invalidResponse();
+    return result;
+}
+/** Copy and validate before awaiting transport, so caller mutations cannot change the signed intent. */
+export function exactActionInput(value) {
+    const input = record(value);
+    const allowed = ['accountId', 'accountAddress', 'chainId', 'action', 'tokenAddress', 'amount', 'recipient', 'tokenOutAddress', 'maxSlippageBps'];
+    if (Object.keys(input).some(key => !allowed.includes(key)))
+        invalidResponse();
+    resourceId(input.accountId);
+    hex(input.accountAddress, 20);
+    hex(input.tokenAddress, 20);
+    integer(input.amount);
+    if (!Number.isSafeInteger(input.chainId) || Number(input.chainId) <= 0)
+        invalidResponse();
+    if (input.action === 'transfer') {
+        hex(input.recipient, 20);
+        if (input.tokenOutAddress !== undefined || input.maxSlippageBps !== undefined)
+            invalidResponse();
+    }
+    else if (input.action === 'swap') {
+        hex(input.tokenOutAddress, 20);
+        if (input.recipient !== undefined || (input.maxSlippageBps !== undefined &&
+            (!Number.isInteger(input.maxSlippageBps) || Number(input.maxSlippageBps) < 1 || Number(input.maxSlippageBps) > 1000)))
+            invalidResponse();
+    }
+    else
+        invalidResponse();
+    return Object.freeze({ ...value, accountAddress: getAddress(value.accountAddress), tokenAddress: getAddress(value.tokenAddress),
+        ...(value.recipient !== undefined ? { recipient: getAddress(value.recipient) } : {}),
+        ...(value.tokenOutAddress !== undefined ? { tokenOutAddress: getAddress(value.tokenOutAddress) } : {}),
+    });
+}
+export function actionBinding(value, action) {
+    resourceId(value.delegationId);
+    hex(value.permissionId, 32);
+    hex(value.executorAddress, 20);
+    integer(value.maxGasCostWei);
+    if (action.action === 'swap') {
+        const swap = value;
+        hex(swap.routerAddress, 20);
+        integer(swap.minAmountOut);
+        if (swap.verifyRoute !== undefined && typeof swap.verifyRoute !== 'function')
+            invalidResponse();
+    }
+    return Object.freeze({ ...value, executorAddress: getAddress(value.executorAddress),
+        ...(action.action === 'swap' ? { routerAddress: getAddress(value.routerAddress) } : {}),
+    });
+}
+/** Validate the actual call and recompute its chain-bound v0.7 hash before handing it to a signer. */
+export async function validateExactAction(value, input, binding) {
+    try {
+        const build = record(value);
+        const context = record(build.execution);
+        const wire = unsignedUserOp(build.userOp);
+        const op = Object.freeze({ ...wire, sender: getAddress(wire.sender), entryPoint: getAddress(wire.entryPoint) });
+        hex(build.userOpHash, 32);
+        if (build.intentType !== 'delegated_action' || record(build.simulation).willSucceed !== true ||
+            context.accountId !== input.accountId || !same(context.accountAddress, input.accountAddress) ||
+            context.chainId !== input.chainId || context.action !== input.action || context.amount !== input.amount ||
+            !same(context.tokenAddress, input.tokenAddress) || context.delegationId !== binding.delegationId ||
+            !same(context.permissionId, binding.permissionId) || context.gasMethod !== 'native' ||
+            !same(op.sender, input.accountAddress) || op.chainId !== input.chainId || !same(op.entryPoint, entryPoint07Address) ||
+            op.factory != null || op.factoryData != null || op.paymaster != null || op.paymasterData != null ||
+            op.paymasterVerificationGasLimit != null || op.paymasterPostOpGasLimit != null)
+            invalidResponse();
+        const nonce = userOpQuantity(op.nonce);
+        if (nonce >> 64n !== sessionKey)
+            invalidResponse();
+        const callGasLimit = userOpQuantity(op.callGasLimit, 128);
+        const verificationGasLimit = userOpQuantity(op.verificationGasLimit, 128);
+        const preVerificationGas = userOpQuantity(op.preVerificationGas);
+        const maxFeePerGas = userOpQuantity(op.maxFeePerGas, 128);
+        const maxPriorityFeePerGas = userOpQuantity(op.maxPriorityFeePerGas, 128);
+        if (maxPriorityFeePerGas > maxFeePerGas ||
+            (callGasLimit + verificationGasLimit + preVerificationGas) * maxFeePerGas > integer(binding.maxGasCostWei))
+            invalidResponse();
+        // Smart Sessions requires raw Kernel execute, without an owner executeUserOp wrapper.
+        const rawCallData = op.callData;
+        let inner;
+        if (input.action === 'transfer') {
+            if (!same(context.recipient, input.recipient) || context.tokenOutAddress !== undefined || context.maxSlippageBps !== undefined)
+                invalidResponse();
+            const native = same(input.tokenAddress, zeroAddress);
+            inner = encodeFunctionData({ abi: grantAbi, functionName: 'executeUnderGrant', args: [binding.permissionId,
+                    (native ? input.recipient : input.tokenAddress), native ? integer(input.amount) : 0n,
+                    native ? '0x' : encodeFunctionData({ abi: transferAbi, functionName: 'transfer', args: [input.recipient, integer(input.amount)] }),
+                ] });
+        }
+        else {
+            const swap = binding;
+            if (!same(context.tokenOutAddress, input.tokenOutAddress) || context.recipient !== undefined ||
+                context.maxSlippageBps !== (input.maxSlippageBps ?? 50))
+                invalidResponse();
+            const kernel = decodeFunctionData({ abi: kernelAbi, data: rawCallData });
+            const packed = kernel.args[1];
+            const decoded = decodeFunctionData({ abi: grantAbi, data: `0x${packed.slice(106)}` });
+            if (decoded.functionName !== 'executeUnderGrantWithAllowance')
+                invalidResponse();
+            const routeData = decoded.args[5];
+            const facts = Object.freeze({ chainId: input.chainId, accountAddress: input.accountAddress,
+                routerAddress: swap.routerAddress, tokenAddress: input.tokenAddress, tokenOutAddress: input.tokenOutAddress,
+                amount: input.amount, minAmountOut: swap.minAmountOut, callData: routeData });
+            if (swap.verifyRoute) {
+                if (await swap.verifyRoute(facts) !== true)
+                    invalidResponse();
+            }
+            else {
+                const route = decodeFunctionData({ abi: swapAbi, data: routeData });
+                const [from, to, amount, minOut, recipient] = route.args;
+                if (!same(from, input.tokenAddress) || !same(to, input.tokenOutAddress) || amount !== integer(input.amount) ||
+                    minOut < integer(swap.minAmountOut) || !same(recipient, input.accountAddress) ||
+                    !same(encodeFunctionData({ abi: swapAbi, functionName: 'swapExactIn', args: route.args }), routeData))
+                    invalidResponse();
+            }
+            inner = encodeFunctionData({ abi: grantAbi, functionName: 'executeUnderGrantWithAllowance', args: [binding.permissionId,
+                    swap.routerAddress, 0n, input.tokenAddress, integer(input.amount), routeData] });
+        }
+        const expected = encodeFunctionData({ abi: kernelAbi, functionName: 'execute', args: [zeroHash,
+                encodePacked(['address', 'uint256', 'bytes'], [binding.executorAddress, 0n, inner])] });
+        if (!same(rawCallData, expected))
+            invalidResponse();
+        const hash = getUserOperationHash({ entryPointAddress: entryPoint07Address, entryPointVersion: '0.7', chainId: input.chainId,
+            userOperation: { sender: op.sender, nonce, callData: op.callData, callGasLimit, verificationGasLimit, preVerificationGas,
+                maxFeePerGas, maxPriorityFeePerGas, signature: '0x' } });
+        if (!same(hash, build.userOpHash))
+            invalidResponse();
+        const execution = Object.freeze({ ...input, delegationId: binding.delegationId, permissionId: binding.permissionId,
+            gasMethod: 'native', ...(input.action === 'swap' ? { maxSlippageBps: input.maxSlippageBps ?? 50 } : {}) });
+        // Whitelist fields instead of forwarding extra server-controlled authorization extensions.
+        const userOp = Object.freeze({ sender: op.sender, chainId: op.chainId, entryPoint: op.entryPoint,
+            nonce: op.nonce, callData: op.callData, callGasLimit: op.callGasLimit, verificationGasLimit: op.verificationGasLimit,
+            preVerificationGas: op.preVerificationGas, maxFeePerGas: op.maxFeePerGas, maxPriorityFeePerGas: op.maxPriorityFeePerGas,
+            signature: '0x' });
+        return { userOp, userOpHash: hash, execution };
+    }
+    catch {
+        return invalidResponse();
+    }
+}
+/** Receipt validation happens after submission, so failure must retain the reconciliation handle. */
+export function exactActionReceipt(value, hash) {
+    try {
+        const receipt = record(value);
+        resourceId(receipt.id);
+        if (!same(receipt.userOpHash, hash) || !['pending', 'included', 'failed'].includes(String(receipt.status)))
+            throw new Error();
+        if (receipt.txHash != null)
+            hex(receipt.txHash, 32);
+        return receipt;
+    }
+    catch {
+        const error = new BotanaryApiError('Botanary returned an invalid receipt. Reconcile using the original operation hash.', 0);
+        error.code = 'invalid_response';
+        error.userOpHash = hash;
+        error.ambiguous = true;
+        throw error;
+    }
+}
+//# sourceMappingURL=exact-action.js.map

package/dist/exact-action.js.map

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

package/dist/fingerprint.d.ts

@@ -0,0 +1,21 @@
+import type { Hex } from 'viem';
+/** Encode `bytes` as Crockford Base32. Not meant to round-trip (no decoder here, and slicing the
+ *  result to a shorter display length - see below - deliberately drops the tail) - this is a display
+ *  transform for short human-facing codes, not a data-interchange encoding. */
+export declare function crockfordBase32(bytes: Uint8Array): string;
+/** Bytes of address fingerprint / pairing nonce - chosen for "short to type" over "cryptographically
+ *  weighty", since neither is a secret (see README's "why intercepting the code alone grants nothing").
+ *  FINGERPRINT_BYTES: ~24 bits, purely a human recognition aid - the full address is always available
+ *  via get_identity for exact verification, so collisions here cost nothing but a moment's "hm, two
+ *  agents look similar", not a security property.
+ *  NONCE_BYTES: ~40 bits of fresh randomness per pairing code, the thing that actually makes each code
+ *  single-use in practice (combined with the short TTL - see pairing-code.ts). */
+export declare const FINGERPRINT_BYTES = 3;
+export declare const NONCE_BYTES = 5;
+/** A short, deterministic, human-typable id for an address - always the same for the same address.
+ *  Purely a display/recognition aid (see module doc); the address itself is the real identifier. */
+export declare function deriveFingerprint(address: Hex): string;
+/** A fresh random nonce for one pairing code. Never derived from the key - pure randomness, so a new
+ *  call can never be predicted from a previous one. */
+export declare function generatePairingNonce(): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAOhC;;+EAE+E;AAC/E,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAgBzD;AAED;;;;;;kFAMkF;AAClF,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B;oGACoG;AACpG,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,GAAG,GAAG,MAAM,CAGtD;AAED;uDACuD;AACvD,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}

package/dist/fingerprint.js

@@ -0,0 +1,47 @@
+import { randomBytes } from 'node:crypto';
+import { hexToBytes } from 'viem';
+// Crockford Base32: 32 symbols, excludes I/L/O/U so nothing is ambiguous when read aloud or typed by
+// hand (no risk of confusing 0/O, 1/I/L), case-insensitive by convention. This is the same alphabet
+// family used by ULIDs and plenty of other human-facing codes for exactly this reason.
+const ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+/** Encode `bytes` as Crockford Base32. Not meant to round-trip (no decoder here, and slicing the
+ *  result to a shorter display length - see below - deliberately drops the tail) - this is a display
+ *  transform for short human-facing codes, not a data-interchange encoding. */
+export function crockfordBase32(bytes) {
+    let bitBuffer = 0;
+    let bitCount = 0;
+    let output = '';
+    for (const byte of bytes) {
+        bitBuffer = (bitBuffer << 8) | byte;
+        bitCount += 8;
+        while (bitCount >= 5) {
+            output += ALPHABET[(bitBuffer >>> (bitCount - 5)) & 0x1f];
+            bitCount -= 5;
+        }
+    }
+    if (bitCount > 0) {
+        output += ALPHABET[(bitBuffer << (5 - bitCount)) & 0x1f];
+    }
+    return output;
+}
+/** Bytes of address fingerprint / pairing nonce - chosen for "short to type" over "cryptographically
+ *  weighty", since neither is a secret (see README's "why intercepting the code alone grants nothing").
+ *  FINGERPRINT_BYTES: ~24 bits, purely a human recognition aid - the full address is always available
+ *  via get_identity for exact verification, so collisions here cost nothing but a moment's "hm, two
+ *  agents look similar", not a security property.
+ *  NONCE_BYTES: ~40 bits of fresh randomness per pairing code, the thing that actually makes each code
+ *  single-use in practice (combined with the short TTL - see pairing-code.ts). */
+export const FINGERPRINT_BYTES = 3;
+export const NONCE_BYTES = 5;
+/** A short, deterministic, human-typable id for an address - always the same for the same address.
+ *  Purely a display/recognition aid (see module doc); the address itself is the real identifier. */
+export function deriveFingerprint(address) {
+    const bytes = hexToBytes(address);
+    return crockfordBase32(bytes.slice(0, FINGERPRINT_BYTES));
+}
+/** A fresh random nonce for one pairing code. Never derived from the key - pure randomness, so a new
+ *  call can never be predicted from a previous one. */
+export function generatePairingNonce() {
+    return crockfordBase32(randomBytes(NONCE_BYTES));
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAGlC,qGAAqG;AACrG,oGAAoG;AACpG,uFAAuF;AACvF,MAAM,QAAQ,GAAG,kCAAkC,CAAC;AAEpD;;+EAE+E;AAC/E,MAAM,UAAU,eAAe,CAAC,KAAiB;IAC/C,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,SAAS,GAAG,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;QACpC,QAAQ,IAAI,CAAC,CAAC;QACd,OAAO,QAAQ,IAAI,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,QAAQ,CAAC,CAAC,SAAS,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;YAC1D,QAAQ,IAAI,CAAC,CAAC;QAChB,CAAC;IACH,CAAC;IACD,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QACjB,MAAM,IAAI,QAAQ,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;kFAMkF;AAClF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AACnC,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAE7B;oGACoG;AACpG,MAAM,UAAU,iBAAiB,CAAC,OAAY;IAC5C,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;IAClC,OAAO,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED;uDACuD;AACvD,MAAM,UAAU,oBAAoB;IAClC,OAAO,eAAe,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC;AACnD,CAAC"}