@botanary/agent 0.1.0-alpha.1 → 0.1.0-alpha.12

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.1.0-alpha.11
+
+- Redact credential material from transport errors and validate typed runtime responses with strict timestamps.
+- Reject invalid display amounts before transport and enforce the documented pairing-code configuration and wire format.
+
+## 0.1.0-alpha.7
+
+- Republish the empty-recipient unrestricted-mandate fix through the exact protected pnpm artifact path.
+
+## 0.1.0-alpha.6
+
+- Treat an empty mandate recipient list as unrestricted while preserving exact membership checks for non-empty recipient allowlists.
+
+## 0.1.0-alpha.5
+
+- Add `prepareAction({ mandate, action })` for exact Base Sepolia transfers from a confirmed mandate projection.
+- Allow a mandate with strict active on-chain state to prepare an action while its durable creation operation still awaits final settlement.
+- Return deterministic typed refusals for over-limit, wrong-recipient, inactive, expired, and revoked mandates before signing or transport.
+- Require a trusted per-runtime native gas ceiling for the mandate facade and preserve the existing exact action hash, nonce-lane, one-shot submission, and reconciliation checks.
+
+## Unreleased - protected artifact build
+
+- No public method changed. `AgentRuntime` still contains no planning, tool selection, or
+  operation/grant/API-payment compilation and no route or provider selection - the hosted platform
+  re-resolves both swap legs from its own per-chain manifest. The only local trust logic is the exact
+  challenge/digest verifier behind `prepareExactAction` and `registerAgent`, plus one-shot signing and
+  submission fencing; both signer-defense units carry a written threat argument in
+  `packages/protected-boundary/inventory.json`.
+- Ship an explicit release build: `dist/index.js` is bundled and minified with esbuild, comments
+  removed, `viem` and `openapi-fetch` kept external, `node:` built-ins left in place, and no
+  JavaScript source maps or declaration maps are emitted.
+- `pnpm run audit:artifact` proves the exact tarball contains only allowlisted declarations, bundled
+  runtime, README, changelog, manifest and licence.
+- `pnpm check:inventory` classifies all 13 runtime exports and fails CI on drift.
+- No new live-chain or deployed-platform evidence.
+
 ## 0.1.0-alpha.1
 
 - Recover durable API payment status without signing or forwarding an existing submission again.

package/README.md

@@ -1,7 +1,6 @@
 # @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.
+Version 0.1.0-alpha.12, canonical API contract 2026-09-12. MIT licensed. Node 22 or later.
 
 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
@@ -69,6 +68,31 @@ No mainnet grant capability is added here.
 
 ## Exact execution
 
+For the developer-first mandate flow, configure one trusted native gas ceiling when constructing the
+runtime, then pass the confirmed mandate projection directly. The facade accepts transfer only and
+maps `amountRaw` without floating-point conversion:
+
+```ts
+const runtime = new AgentRuntime(agentSigner, { maxGasCostWei: '10000000000000000' });
+const prepared = await runtime.prepareAction({
+  mandate,
+  action: { type: 'transfer', tokenAddress, recipient, amountRaw: '1000000' },
+});
+if (prepared.status === 'refused') {
+  // No transaction was submitted. Render reason and remainingRaw as policy evidence.
+  return prepared;
+}
+remember(prepared.userOpHash);
+return prepared.submit();
+```
+
+The projection must report confirmed creation, active API access, observed active chain authority,
+the exact account, agent, permission, executor, policy, and remaining limit. The package rechecks the
+runtime agent identity. Over-limit, wrong-recipient, inactive, expired, and revoked requests return a
+typed refusal before build or signing. An allowed request continues through the same exact call,
+nonce-lane, gas-ceiling, hash, signature, one-shot submission, and reconciliation checks described
+below. OpenAI integration, key loading, persistence, and retries remain host responsibilities.
+
 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.
@@ -118,6 +142,20 @@ API access disablement and on-chain permission revocation are separate. Disablin
 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.
+`pnpm test`, `pnpm build`, `pnpm check:inventory`, `pnpm run audit:artifact`, and `pnpm test:packed`.
+Install the independent SDK package before the packed check. The CLI and MCP package integration
+checks live in their private repositories.
+
+## What ships in the npm tarball
+
+Allowlisted declarations (no declaration maps), one bundled and minified `dist/index.js` (no source
+maps, no comments; `viem`, `openapi-fetch` and `node:` built-ins external), this README, the
+changelog and `LICENSE`. `pnpm run audit:artifact` verifies the exact tarball.
+
+Every runtime export is classified in
+[`docs/specs/2026-09-10-protected-sdk-integration-boundary.inventory.md`](../../docs/specs/2026-09-10-protected-sdk-integration-boundary.inventory.md).
+`AgentRuntime` carries no planning, tool selection, compilation, or route/provider selection - the
+hosted platform re-resolves both swap legs from its own manifest. The only local trust logic is the
+exact challenge/digest verifier behind `prepareExactAction` and `registerAgent` plus one-shot
+signing and submission fencing, each with a written threat argument. No important logic is
+distributed; minification is not concealment.

package/dist/errors.d.ts

@@ -1,25 +1,6 @@
-/** 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;
@@ -27,23 +8,5 @@ export declare class BotanaryApiError extends Error {
     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);
+    constructor(message: string, status: number, details?: Record<string, unknown> | null, retryAfterSeconds?: number | null);
 }
-//# sourceMappingURL=errors.d.ts.map

package/dist/exact-action.d.ts

@@ -7,7 +7,6 @@ export interface AgentActionBinding {
     delegationId: string;
     permissionId: Hex;
     executorAddress: Hex;
-    /** Maximum native gas cost for this operation, in wei. */
     maxGasCostWei: string;
 }
 export interface SwapRouteFacts {
@@ -23,26 +22,80 @@ export interface SwapRouteFacts {
 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 status: 'prepared';
     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 interface AgentMandateProjection {
+    readonly id: string;
+    readonly accountId: string;
+    readonly accountAddress: Hex;
+    readonly agentAddress: Hex;
+    readonly chainId: 84532;
+    readonly permissionId: Hex;
+    readonly grantExecutor: Hex;
+    readonly apiAccess: string;
+    readonly createStatus: string;
+    readonly revokeStatus: string | null;
+    readonly policy: {
+        readonly budgets: readonly {
+            readonly token: Hex;
+            readonly amountRaw: string;
+        }[];
+        readonly perActionMaxRaw: string | null;
+        readonly recipients: readonly Hex[];
+        readonly maxActions: number | null;
+        readonly expiresAt: string;
+    };
+    readonly chainState: {
+        readonly status: string;
+        readonly remaining?: readonly {
+            readonly token: Hex;
+            readonly remainingRaw: string;
+        }[];
+    };
+}
+export interface MandateTransferInput {
+    readonly mandate: AgentMandateProjection;
+    readonly action: {
+        readonly type: 'transfer';
+        readonly tokenAddress: Hex;
+        readonly recipient: Hex;
+        readonly amountRaw: string;
+    };
+}
+export interface MandateSwapInput {
+    readonly mandate: AgentMandateProjection;
+    readonly action: {
+        readonly type: 'swap';
+        readonly tokenAddress: Hex;
+        readonly tokenOutAddress: Hex;
+        readonly amountRaw: string;
+        readonly routerAddress: Hex;
+        readonly minAmountOutRaw: string;
+        readonly maxSlippageBps?: number;
+        readonly verifyRoute?: (facts: SwapRouteFacts) => Promise<boolean> | boolean;
+    };
+}
+export type MandateActionInput = MandateTransferInput | MandateSwapInput;
+export interface AgentPolicyRefusal {
+    readonly status: 'refused';
+    readonly reason: 'over_per_action_max' | 'wrong_recipient' | 'unbudgeted_swap_leg' | 'mandate_inactive' | 'mandate_revoked' | 'mandate_expired';
+    readonly transactionSubmitted: false;
+    readonly requestedAmountRaw: string;
+    readonly perActionMaxRaw: string | null;
+    readonly remainingRaw: string | null;
+}
 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/fingerprint.d.ts

@@ -1,21 +1,6 @@
 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/generated/routes.d.ts

@@ -65,4 +65,3 @@ export declare const AGENT_ROUTES: readonly [{
     readonly method: "get";
     readonly path: "/apis/calls/relay/{id}";
 }];
-//# sourceMappingURL=routes.d.ts.map