botanary-mcp 0.4.2 → 0.6.0

package/dist/bin/botanary-mcp.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=botanary-mcp.d.ts.map

package/dist/bin/botanary-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"botanary-mcp.d.ts","sourceRoot":"","sources":["../../bin/botanary-mcp.ts"],"names":[],"mappings":""}

package/dist/src/agent-actions.d.ts

@@ -0,0 +1,44 @@
+import type { AgentRuntime } from './runtime.js';
+export interface ProposePaymentInput {
+    recipient: string;
+    amount: number;
+    tokenSymbol: string;
+    chainId: number;
+}
+export interface ProposeSwapInput {
+    tokenIn: string;
+    tokenOut: string;
+    amountIn: number;
+    chainId: number;
+    maxSlippageBps?: number;
+}
+/**
+ * Build and relay a payment under this agent's OWN grant. Reads the grant's bounds and permissionId from
+ * the backend (GET /agents/me) FIRST: when there is no grant, the grant is not active, it is on a
+ * different chain, or the amount would exceed its remaining budget or per-action cap, this refuses with
+ * the backend's own numbers rather than attempting anything - it never pretends to send a payment it did
+ * not send. Otherwise it builds the delegated action (POST /delegations/{delegationId}/actions - the ONLY
+ * build lane a session-key signature can validate; never the owner-lane /money/send/build) against THIS
+ * agent's own grant id, then relays it signed with the grant's own session key (POST /userops), returning
+ * the backend's real relay result. This client-side bounds check is a convenience, never the check - the
+ * chain is what actually enforces the grant.
+ */
+export declare function proposePayment(runtime: AgentRuntime, input: ProposePaymentInput): Promise<Record<string, unknown>>;
+/**
+ * Build and relay a SWAP under this agent's OWN grant - sell one token for another, in the account's own
+ * name, without the owner signing. Reads the grant's bounds and permissionId from the backend
+ * (GET /agents/me) FIRST: when there is no grant, the grant is not active, it is on a different chain,
+ * the grant names NO swap venue at all (a transfer-only grant has no allowance action for a swap to
+ * validate against), the token being sold is not the one token its venue pins, or the amount exceeds
+ * that venue's per-swap allowance ceiling, this refuses with the backend's own numbers rather than
+ * attempting anything - it never pretends to have swapped what it did not. Otherwise it builds the
+ * delegated action (POST /delegations/{delegationId}/actions with action: 'swap' - the ONLY build lane a
+ * session-key signature can validate; never the owner-lane /money/swap/build) against THIS agent's own
+ * grant id, then relays it signed with the grant's own session key (POST /userops), returning the
+ * backend's real relay result. The ROUTE is the backend's to choose and the grant pins exactly one
+ * router, so a best route through any other router is declined there, by name - this never picks a venue.
+ * This client-side bounds check is a convenience, never the check - the chain is what actually enforces
+ * the grant.
+ */
+export declare function proposeSwap(runtime: AgentRuntime, input: ProposeSwapInput): Promise<Record<string, unknown>>;
+//# sourceMappingURL=agent-actions.d.ts.map

package/dist/src/agent-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-actions.d.ts","sourceRoot":"","sources":["../../src/agent-actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAKjD,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA8GxH;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAqIlH"}

package/dist/src/agent-actions.js

@@ -0,0 +1,244 @@
+import { describeGrant, findBudgetMeter, missingModuleOf } from './agent-grant-helpers.js';
+import { settleRelayedOp } from './wallet/send-orchestration.js';
+import { setupUrl } from './app-link.js';
+/**
+ * Build and relay a payment under this agent's OWN grant. Reads the grant's bounds and permissionId from
+ * the backend (GET /agents/me) FIRST: when there is no grant, the grant is not active, it is on a
+ * different chain, or the amount would exceed its remaining budget or per-action cap, this refuses with
+ * the backend's own numbers rather than attempting anything - it never pretends to send a payment it did
+ * not send. Otherwise it builds the delegated action (POST /delegations/{delegationId}/actions - the ONLY
+ * build lane a session-key signature can validate; never the owner-lane /money/send/build) against THIS
+ * agent's own grant id, then relays it signed with the grant's own session key (POST /userops), returning
+ * the backend's real relay result. This client-side bounds check is a convenience, never the check - the
+ * chain is what actually enforces the grant.
+ */
+export async function proposePayment(runtime, input) {
+    const { recipient, amount, tokenSymbol, chainId } = input;
+    const self = await runtime.me();
+    if (!self.grant) {
+        return { proposed: false, reason: 'no_grant', message: `${describeGrant(self)} Nothing was built or sent.` };
+    }
+    const grant = self.grant;
+    if (grant.status !== 'active') {
+        return {
+            proposed: false,
+            reason: 'grant_not_active',
+            message: `This grant is "${grant.status}", not active, so it cannot be spent under. Nothing was ` +
+                'built or sent. Use request_approval to ask the owner directly.',
+        };
+    }
+    if (grant.chainId !== chainId) {
+        return {
+            proposed: false,
+            reason: 'wrong_chain',
+            message: `This grant is on chain ${grant.chainId} (${grant.chain}), not chain ${chainId}. Nothing ` +
+                'was built or sent. Use request_approval if this payment genuinely needs that chain.',
+        };
+    }
+    const meter = findBudgetMeter(grant, tokenSymbol);
+    if (!meter) {
+        return {
+            proposed: false,
+            reason: 'token_not_budgeted',
+            message: `This grant has no budget for ${tokenSymbol}. Budgeted tokens: ` +
+                `${grant.policySet.budgets.map((b) => b.token.symbol).join(', ') || 'none'}. Nothing was ` +
+                'built or sent. Use request_approval instead.',
+        };
+    }
+    if (amount > meter.remaining) {
+        return {
+            proposed: false,
+            reason: 'over_budget',
+            message: `This grant has ${meter.remaining} ${tokenSymbol} remaining (of ${meter.limit} total); ` +
+                `${amount} ${tokenSymbol} would exceed it. Nothing was built or sent. Use request_approval ` +
+                'to ask the owner for this specific payment.',
+        };
+    }
+    const perActionMax = grant.policySet.perActionMax;
+    if (perActionMax && perActionMax.token.symbol.toUpperCase() === tokenSymbol.toUpperCase() && amount > perActionMax.amount) {
+        return {
+            proposed: false,
+            reason: 'over_per_action_max',
+            message: `This grant caps a single action at ${perActionMax.amount} ${tokenSymbol}; ${amount} ` +
+                'exceeds it. Nothing was built or sent. Use request_approval instead.',
+        };
+    }
+    // Within the client-read bounds - build the delegated action AGAINST THIS AGENT'S OWN GRANT ID
+    // (grant.id, from GET /agents/me - never invented, never another agent's), then relay it signed
+    // with the grant's own session key. This check is a convenience, never the check: Smart Sessions'
+    // own on-chain policies are what actually enforce the grant when the relay lands, and the backend
+    // itself refuses (403, named reason) a delegation id that does not name this agent.
+    let build;
+    try {
+        build = await runtime.buildDelegatedAction({ delegationId: grant.id, recipient, amount, token: tokenSymbol });
+    }
+    catch (e) {
+        // The one refusal with a remedy the OWNER can act on in a browser and this agent cannot act on
+        // at all. Hand back the address of that remedy rather than a bare "cannot succeed" - and say
+        // plainly that retrying is pointless, because nothing about a retry installs a module.
+        const missing = missingModuleOf(e);
+        if (!missing)
+            throw e;
+        return {
+            proposed: false,
+            reason: 'account_setup_required',
+            missingModule: missing,
+            setupUrl: setupUrl(runtime.apiBaseUrl, grant.chainId),
+            message: `This account is missing ${missing} on chain ${grant.chainId} (${grant.chain}), so a ` +
+                'payment under this grant cannot succeed. Nothing was built or sent, and retrying will ' +
+                'fail identically - installing a module is an authority change only the owner can sign, ' +
+                'and a session key cannot do it. Open the setupUrl above in a browser, sign the one-time ' +
+                'setup, then ask me to try this payment again.',
+        };
+    }
+    const token = await runtime.ensureSession();
+    const relay = await runtime.spendUnderGrant(build.userOp, build.userOpHash, grant.permissionId, token, build.intentType);
+    // Follow the op rather than reporting a bare `pending` and going quiet. The op id comes from the
+    // backend's own relay response - never invented here.
+    const opId = typeof relay?.id === 'string' ? relay.id : null;
+    if (!opId)
+        return { proposed: true, settled: false, userOpHash: build.userOpHash, relay };
+    // THE RELAY HAS ALREADY SUCCEEDED by this line - the backend holds the signed op and gave us its
+    // id. Everything below is FOLLOW-UP, so a throw there (a 500 on the status read, a session re-mint
+    // that fails, a dropped connection) is not a failed payment and must never be reported as one.
+    // Unwrapped, it would propagate as a bare error carrying neither the opId nor the do-not-resend
+    // instruction - and the agent's natural next move, resending, would move real money twice. That
+    // whole discipline lives in `settleRelayedOp`, shared with `proposeSwap` so the two can never
+    // drift into describing the same three outcomes differently.
+    return settleRelayedOp(runtime, opId, build.userOpHash, 'payment', { amount, token: tokenSymbol }, `NOTHING moved: no ${tokenSymbol} left the account, the recipient received nothing, ` +
+        'and the grant budget was not spent.');
+}
+/**
+ * Build and relay a SWAP under this agent's OWN grant - sell one token for another, in the account's own
+ * name, without the owner signing. Reads the grant's bounds and permissionId from the backend
+ * (GET /agents/me) FIRST: when there is no grant, the grant is not active, it is on a different chain,
+ * the grant names NO swap venue at all (a transfer-only grant has no allowance action for a swap to
+ * validate against), the token being sold is not the one token its venue pins, or the amount exceeds
+ * that venue's per-swap allowance ceiling, this refuses with the backend's own numbers rather than
+ * attempting anything - it never pretends to have swapped what it did not. Otherwise it builds the
+ * delegated action (POST /delegations/{delegationId}/actions with action: 'swap' - the ONLY build lane a
+ * session-key signature can validate; never the owner-lane /money/swap/build) against THIS agent's own
+ * grant id, then relays it signed with the grant's own session key (POST /userops), returning the
+ * backend's real relay result. The ROUTE is the backend's to choose and the grant pins exactly one
+ * router, so a best route through any other router is declined there, by name - this never picks a venue.
+ * This client-side bounds check is a convenience, never the check - the chain is what actually enforces
+ * the grant.
+ */
+export async function proposeSwap(runtime, input) {
+    const { tokenIn, tokenOut, amountIn, chainId, maxSlippageBps } = input;
+    // BOUNDS FIRST, exactly as proposePayment does, and for the same reason: the refusals below are
+    // the ones this side can make honestly from backend-reported facts, and making them here means an
+    // out-of-grant swap costs no build, no signature and no relay.
+    const self = await runtime.me();
+    if (!self.grant) {
+        return { proposed: false, reason: 'no_grant', message: `${describeGrant(self)} Nothing was built or sent.` };
+    }
+    const grant = self.grant;
+    if (grant.status !== 'active') {
+        return {
+            proposed: false,
+            reason: 'grant_not_active',
+            message: `This grant is "${grant.status}", not active, so it cannot be spent under. Nothing was ` +
+                'built or sent. Use request_approval to ask the owner directly.',
+        };
+    }
+    if (grant.chainId !== chainId) {
+        return {
+            proposed: false,
+            reason: 'wrong_chain',
+            message: `This grant is on chain ${grant.chainId} (${grant.chain}), not chain ${chainId}. Nothing ` +
+                'was built or sent. A grant\'s allowance, meter and session are per-chain storage on one ' +
+                'account, so there is nothing on another chain for it to bound. Use request_approval if ' +
+                'this swap genuinely needs that chain.',
+        };
+    }
+    // THE REFUSAL THAT IS NOT A BUDGET CHECK. A grant compiled with no `swapVenue` carries only the
+    // transfer action - its session has no allowance entrypoint at all, so a swap op under it is not
+    // "over budget", it is unvalidatable. The backend records the venue on the grant precisely so
+    // this is answerable without a chain read: a compiled session cannot be read back from a
+    // permissionId, and inventing an answer here would mean relaying an op that always reverts.
+    const venue = grant.policySet.swapVenue;
+    if (!venue) {
+        return {
+            proposed: false,
+            reason: 'no_swap_venue',
+            message: 'This grant was given for transfers only - it names no swap venue, so its session carries ' +
+                'no allowance action for a swap to validate against, and no amount is small enough to ' +
+                'change that. Nothing was built or sent. Ask the owner for a new grant naming the router ' +
+                'and token it may swap, or use request_approval for this one swap.',
+        };
+    }
+    if (venue.token.symbol.toUpperCase() !== tokenIn.toUpperCase()) {
+        return {
+            proposed: false,
+            reason: 'token_not_venue_token',
+            message: `This grant may only swap ${venue.token.symbol}, not ${tokenIn} - its session pins the ` +
+                'sold token exactly, and any other would be refused in validation. Nothing was built or ' +
+                'sent. Use request_approval instead.',
+        };
+    }
+    if (amountIn > venue.maxAllowance) {
+        return {
+            proposed: false,
+            reason: 'over_venue_allowance',
+            message: `This grant allows at most ${venue.maxAllowance} ${venue.token.symbol} per swap; ` +
+                `${amountIn} ${tokenIn} exceeds it. Nothing was built or sent. Use request_approval to ask ` +
+                'the owner for this specific swap.',
+        };
+    }
+    // The grant's ordinary spend meter applies TOO - the venue ceiling caps one swap, the budget caps
+    // the lifetime - so a swap within the ceiling but over what is left is still refused here, with
+    // the backend's own remaining figure rather than a guess.
+    const meter = findBudgetMeter(grant, tokenIn);
+    if (meter && amountIn > meter.remaining) {
+        return {
+            proposed: false,
+            reason: 'over_budget',
+            message: `This grant has ${meter.remaining} ${tokenIn} remaining (of ${meter.limit} total); ` +
+                `${amountIn} ${tokenIn} would exceed it. Nothing was built or sent. Use request_approval ` +
+                'to ask the owner for this specific swap.',
+        };
+    }
+    // Within the client-read bounds - build AGAINST THIS AGENT'S OWN GRANT ID (grant.id, from
+    // GET /agents/me), then relay it signed with the grant's own session key. The router is the
+    // BACKEND's to resolve: it quotes the route, checks it against the one router the venue pins, and
+    // declines by name when they disagree. This side never picks a venue.
+    let build;
+    try {
+        build = await runtime.buildDelegatedSwap({
+            delegationId: grant.id,
+            tokenIn,
+            tokenOut,
+            amountIn,
+            ...(maxSlippageBps != null ? { maxSlippageBps } : {}),
+        });
+    }
+    catch (e) {
+        // Same one refusal with an owner-only remedy the payment lane has - see its comment. A session
+        // key cannot install a module, so retrying is pointless and saying so is the honest answer.
+        const missing = missingModuleOf(e);
+        if (!missing)
+            throw e;
+        return {
+            proposed: false,
+            reason: 'account_setup_required',
+            missingModule: missing,
+            setupUrl: setupUrl(runtime.apiBaseUrl, grant.chainId),
+            message: `This account is missing ${missing} on chain ${grant.chainId} (${grant.chain}), so a ` +
+                'swap under this grant cannot succeed. Nothing was built or sent, and retrying will ' +
+                'fail identically - installing a module is an authority change only the owner can sign, ' +
+                'and a session key cannot do it. Open the setupUrl above in a browser, sign the one-time ' +
+                'setup, then ask me to try this swap again.',
+        };
+    }
+    const token = await runtime.ensureSession();
+    const relay = await runtime.spendUnderGrant(build.userOp, build.userOpHash, grant.permissionId, token, build.intentType);
+    const opId = typeof relay?.id === 'string' ? relay.id : null;
+    if (!opId)
+        return { proposed: true, settled: false, userOpHash: build.userOpHash, relay };
+    // THE RELAY HAS ALREADY SUCCEEDED by this line - see `settleRelayedOp`, which owns the three
+    // outcomes from here and is the SAME code proposePayment settles through.
+    return settleRelayedOp(runtime, opId, build.userOpHash, 'swap', { amount: amountIn, token: tokenIn }, `NOTHING moved: no ${tokenIn} left the account, no ${tokenOut} was received, ` +
+        'and the grant budget was not spent.');
+}
+//# sourceMappingURL=agent-actions.js.map

package/dist/src/agent-actions.js.map

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

package/dist/src/agent-grant-helpers.d.ts

@@ -0,0 +1,13 @@
+import type { AgentGrantView, AgentSelf, SpendMeterView } from './runtime.js';
+/** The backend names a missing setup module in structured `details.missingModule` - see
+ *  `BotanaryApiError.details`. Null for every other failure, so callers fall through to normal handling. */
+export declare function missingModuleOf(e: unknown): string | null;
+/** Plain-English rendering of `GET /agents/me`'s `grant` field - built entirely from backend-reported
+ *  data (never a fabricated number), shared by `what_may_i_do` and the `propose_payment`/`propose_swap`
+ *  refusal paths so no two tools describe the same grant two different ways. */
+export declare function describeGrant(self: AgentSelf): string;
+/** The spend meter for `tokenSymbol` on this grant, or undefined when the grant budgets no such token -
+ *  `spentToDate` is "one meter per budget, in the SAME order as policySet.budgets" (backend's own
+ *  invariant, `Delegation.spentToDate`'s doc comment), which is what makes this a plain index lookup. */
+export declare function findBudgetMeter(grant: AgentGrantView, tokenSymbol: string): SpendMeterView | undefined;
+//# sourceMappingURL=agent-grant-helpers.d.ts.map

package/dist/src/agent-grant-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-grant-helpers.d.ts","sourceRoot":"","sources":["../../src/agent-grant-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9E;4GAC4G;AAC5G,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAIzD;AAED;;gFAEgF;AAChF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAqBrD;AAED;;yGAEyG;AACzG,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAGtG"}

package/dist/src/agent-grant-helpers.js

@@ -0,0 +1,36 @@
+/** The backend names a missing setup module in structured `details.missingModule` - see
+ *  `BotanaryApiError.details`. Null for every other failure, so callers fall through to normal handling. */
+export function missingModuleOf(e) {
+    const details = e?.details;
+    const name = details?.missingModule;
+    return typeof name === 'string' && name.length > 0 ? name : null;
+}
+/** Plain-English rendering of `GET /agents/me`'s `grant` field - built entirely from backend-reported
+ *  data (never a fabricated number), shared by `what_may_i_do` and the `propose_payment`/`propose_swap`
+ *  refusal paths so no two tools describe the same grant two different ways. */
+export function describeGrant(self) {
+    const boundTo = self.accountAddress ? ` on account ${self.accountAddress}` : '';
+    if (!self.grant) {
+        return (`Nothing yet - this agent is connected${boundTo} but has not been granted anything. It can read ` +
+            `balances and draft a payment (propose_payment will explain exactly why it refuses to relay one), ` +
+            `but it cannot spend. Ask your owner to create a grant naming this agent's address ` +
+            `(${self.address}) in Botanary, or call request_approval to ask for one specific payment right ` +
+            `now.${self.accountAddress
+                ? ` If ${self.accountAddress} is not the account you have open in Botanary, you are signed in ` +
+                    `as a different owner - that, not a missing grant, is why this agent is not in your list.`
+                : ''}`);
+    }
+    const g = self.grant;
+    const meters = g.spentToDate
+        .map((m) => `${m.remaining} ${m.token.symbol} remaining of ${m.limit}${m.expiresAt ? ` (until ${m.expiresAt})` : ''}`)
+        .join('; ');
+    return `Grant status: ${g.status}. ${g.humanSummary}${meters ? ` Remaining: ${meters}.` : ''}`;
+}
+/** The spend meter for `tokenSymbol` on this grant, or undefined when the grant budgets no such token -
+ *  `spentToDate` is "one meter per budget, in the SAME order as policySet.budgets" (backend's own
+ *  invariant, `Delegation.spentToDate`'s doc comment), which is what makes this a plain index lookup. */
+export function findBudgetMeter(grant, tokenSymbol) {
+    const idx = grant.policySet.budgets.findIndex((b) => b.token.symbol.toUpperCase() === tokenSymbol.toUpperCase());
+    return idx === -1 ? undefined : grant.spentToDate[idx];
+}
+//# sourceMappingURL=agent-grant-helpers.js.map

package/dist/src/agent-grant-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-grant-helpers.js","sourceRoot":"","sources":["../../src/agent-grant-helpers.ts"],"names":[],"mappings":"AAEA;4GAC4G;AAC5G,MAAM,UAAU,eAAe,CAAC,CAAU;IACxC,MAAM,OAAO,GAAI,CAAyD,EAAE,OAAO,CAAC;IACpF,MAAM,IAAI,GAAG,OAAO,EAAE,aAAa,CAAC;IACpC,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACnE,CAAC;AAED;;gFAEgF;AAChF,MAAM,UAAU,aAAa,CAAC,IAAe;IAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,eAAe,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAChF,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAChB,OAAO,CACL,wCAAwC,OAAO,kDAAkD;YACjG,mGAAmG;YACnG,oFAAoF;YACpF,IAAI,IAAI,CAAC,OAAO,gFAAgF;YAChG,OACE,IAAI,CAAC,cAAc;gBACjB,CAAC,CAAC,OAAO,IAAI,CAAC,cAAc,mEAAmE;oBAC7F,0FAA0F;gBAC5F,CAAC,CAAC,EACN,EAAE,CACH,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;IACrB,MAAM,MAAM,GAAG,CAAC,CAAC,WAAW;SACzB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,iBAAiB,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;SACrH,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,iBAAiB,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,YAAY,GAAG,MAAM,CAAC,CAAC,CAAC,eAAe,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AACjG,CAAC;AAED;;yGAEyG;AACzG,MAAM,UAAU,eAAe,CAAC,KAAqB,EAAE,WAAmB;IACxE,MAAM,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,WAAW,CAAC,WAAW,EAAE,CAAC,CAAC;IACjH,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;AACzD,CAAC"}

package/dist/src/api-client.d.ts

@@ -0,0 +1,57 @@
+/** 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;
+    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);
+}
+/** JSON in and out, throwing the SERVER's own message rather than a generic one - whoever built this
+ *  agent needs the reason, not "request failed" (§6-40, one layer up from the chain). */
+export declare class BotanaryApiClient {
+    #private;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(baseUrl: string, fetchImpl?: typeof fetch);
+    post<T>(path: string, body: unknown, token?: string): Promise<T>;
+    /** GET has no body - a query string, when one is needed, belongs in `path` itself (callers below never
+     *  put a token or anything secret there; see test/no-leak.spec.ts). */
+    get<T>(path: string, token?: string): Promise<T>;
+    /** DELETE request for logout and cleanup operations. No body, authenticated with optional token. */
+    delete<T>(path: string, token?: string): Promise<T>;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/dist/src/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/api-client.ts"],"names":[],"mappings":"AAAA;;;+DAG+D;AAC/D,qBAAa,gBAAiB,SAAQ,KAAK;IAGvC,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;gBAlBzC,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;AAED;yFACyF;AACzF,qBAAa,iBAAiB;;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,OAAO,KAAa;IAG5C,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAItE;2EACuE;IACjE,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAItD,oGAAoG;IAC9F,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CAyC1D"}

package/dist/src/app-link.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Where to send an owner in their browser, derived from the API this server is configured against.
+ *
+ * ITS OWN MODULE, not a corner of `tools.ts`, because both the tool surface and `diagnose` hand out these
+ * links and `tools.ts` already imports `diagnose`. Leaving them in `tools.ts` made that a cycle.
+ */
+/** Derive the Botanary APP origin (what an owner's browser visits) from the API base URL this runtime
+ *  is actually configured against, so a deep link lands on a LOCAL FE when this server is pointed at a
+ *  local stack, rather than always hardcoding production. Recognizes two shapes:
+ *  - Production/staging: the API host is `api.` + the app host (`api.app.botanary.xyz` ->
+ *    `app.botanary.xyz`) - strip that one label.
+ *  - The local docker-compose stack (`../../docker-compose.yml`), which pairs BE :3000 with FE :3001.
+ *  Anything else - an unparseable URL, or a host this function does not recognize - falls back to the
+ *  production app origin: a deep link that opens the wrong (but real) app is safer than one built from
+ *  a guess that resolves nowhere. */
+export declare function deriveAppOrigin(apiBaseUrl: string): string;
+/**
+ * The deep link an owner opens to finish setting up their own account.
+ *
+ * WHY A LINK AT ALL. A missing setup module is the one refusal an agent can neither retry its way out of
+ * nor fix itself: installing a module is an authority change, the op must be signed by the owner's key in
+ * their browser, and a session key must never be able to grant itself new execution modules. So the honest
+ * response is a handoff - and a handoff without an address is a dead end. The owner reading this is usually
+ * the same person reading the terminal, so "ask your owner" is not an instruction, it is a shrug.
+ *
+ * WHAT IT CARRIES. Navigation only: an origin from configuration and a chain id. No signing payload, no
+ * op, no instruction - the page independently asks the backend what is missing and derives the ops from
+ * chain state. Nothing here is interpolated from model-controlled text or from a tool result, which is the
+ * same discipline the deterministic gate follows: a link an agent emits and a human then signs on must not
+ * be steerable by anything the model saw.
+ */
+export declare function setupUrl(apiBaseUrl: string, chainId?: number): string;
+//# sourceMappingURL=app-link.d.ts.map

package/dist/src/app-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-link.d.ts","sourceRoot":"","sources":["../../src/app-link.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;;;;;;;qCAQqC;AACrC,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAc1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAGrE"}

package/dist/src/cli.d.ts

@@ -0,0 +1,14 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { AgentRuntime } from './runtime.js';
+export interface CliDeps {
+    runtime: AgentRuntime;
+    createServer: (runtime: AgentRuntime) => Server;
+    createTransport: () => Parameters<Server['connect']>[0];
+    stdout?: (line: string) => void;
+    stderr?: (line: string) => void;
+}
+/** Runs one CLI invocation and returns the process exit code. Kept free of `process.exit`/signal
+ *  handling so it's directly testable with fake deps - see test/cli.spec.ts. bin/botanary-mcp.ts is
+ *  the (deliberately tiny, untested-by-inspection) shim that wires real deps and process lifecycle. */
+export declare function runCli(argv: string[], deps: CliDeps): Promise<number>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/src/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAiBjD,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,YAAY,CAAC;IACtB,YAAY,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,MAAM,CAAC;IAChD,eAAe,EAAE,MAAM,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxD,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED;;uGAEuG;AACvG,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CA0B3E"}

package/dist/src/diagnose.d.ts

@@ -0,0 +1,37 @@
+import type { AgentRuntime } from './runtime.js';
+export type DiagnoseState = 'no_key' | 'key_unclaimed' | 'backend_unavailable' | 'connected_no_grant' | 'grant_inactive' | 'chain_unusable'
+/** The account is missing a setup module the grant needs. Distinct from `chain_unusable` (the CHAIN
+ *  cannot do this at all) and from `unfunded`/`budget_exhausted` (conditions that resolve on their own
+ *  or with money): this one is permanent until an owner signs an install, so it deserves its own name
+ *  rather than being folded into `degraded`. */
+ | 'setup_required'
+/** The X402PaymentValidator is not installed on the account. Like `setup_required`, this is permanent
+ *  until an owner signs an install - it is ranked BEFORE `unfunded` since installing comes first. */
+ | 'validator_not_installed' | 'unfunded'
+/** The agent's budget for API calls has been exhausted. The owner can refill or issue a new budget. */
+ | 'budget_exhausted' | 'degraded' | 'ready';
+export interface Blocker {
+    /** MCP-LOCAL vocabulary. Deliberately NOT the backend's `DeclineReason` names, which map 1:1 to
+     *  AgentGuard revert selectors - reusing those would imply an on-chain refusal where this is only a
+     *  local read. */
+    code: string;
+    severity: 'blocking' | 'warning';
+    detail: string;
+    nextAction: string;
+}
+export interface DiagnoseReport {
+    state: DiagnoseState;
+    summary: string;
+    blockers: Blocker[];
+    facts: Record<string, unknown>;
+    freshness: Record<string, string>;
+}
+/**
+ * The cold-start question: who am I bound to, is it funded, can this chain do what my grant claims, and
+ * what is stopping the next action. Runs its checks in order and STOPS DESCENDING once the state is
+ * known - it never issues a call whose answer could not change the verdict.
+ *
+ * Never mutates and never signs. Every number it reports is the backend's own.
+ */
+export declare function runDiagnose(runtime: AgentRuntime): Promise<DiagnoseReport>;
+//# sourceMappingURL=diagnose.d.ts.map

package/dist/src/diagnose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose.d.ts","sourceRoot":"","sources":["../../src/diagnose.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAa,MAAM,cAAc,CAAC;AAE5D,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,eAAe,GACf,qBAAqB,GACrB,oBAAoB,GACpB,gBAAgB,GAChB,gBAAgB;AAClB;;;gDAGgD;GAC9C,gBAAgB;AAClB;qGACqG;GACnG,yBAAyB,GACzB,UAAU;AACZ,uGAAuG;GACrG,kBAAkB,GAClB,UAAU,GACV,OAAO,CAAC;AAEZ,MAAM,WAAW,OAAO;IACtB;;sBAEkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,UAAU,GAAG,SAAS,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAeD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CA4PhF"}

package/dist/src/identity/backends/exec.d.ts

@@ -0,0 +1,18 @@
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+export interface ExecOptions {
+    /** Piped to the child's stdin, then the stdin stream is closed. Used to hand a secret to a command
+     *  WITHOUT it ever appearing on argv (and therefore never in `ps`/process-list output) - secret-tool
+     *  and the Windows DPAPI helper both read the secret this way. macOS's `security` CLI has no stdin
+     *  form for the password, which is a real, documented limitation - see macos-keychain.ts. */
+    input?: string;
+}
+export type Exec = (command: string, args: string[], options?: ExecOptions) => Promise<ExecResult>;
+/** The real implementation: spawn a child process (no shell - argv is passed directly, so there is no
+ *  shell-quoting/injection surface), capture stdout/stderr, resolve with the exit code. `spawn` (not
+ *  `execFile`) because we need to write to stdin ourselves and close it explicitly. */
+export declare const nodeExec: Exec;
+//# sourceMappingURL=exec.d.ts.map

package/dist/src/identity/backends/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../../../src/identity/backends/exec.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B;;;iGAG6F;IAC7F,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAEnG;;uFAEuF;AACvF,eAAO,MAAM,QAAQ,EAAE,IAwBtB,CAAC"}

package/dist/src/identity/backends/file-fallback.d.ts

@@ -0,0 +1,6 @@
+import { type KeyBackend } from './types.js';
+export declare function createFileFallbackBackend(filePath?: string): KeyBackend;
+/** Exposed for tests: true only if the file exists and (on POSIX) is exactly owner-rw. Windows mode
+ *  bits are not meaningful via fs.stat, so callers should skip the assertion there. */
+export declare function isPrivateFileMode(filePath: string): Promise<boolean>;
+//# sourceMappingURL=file-fallback.d.ts.map

package/dist/src/identity/backends/file-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-fallback.d.ts","sourceRoot":"","sources":["../../../../src/identity/backends/file-fallback.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,UAAU,EAAmB,MAAM,YAAY,CAAC;AAe9D,wBAAgB,yBAAyB,CAAC,QAAQ,GAAE,MAAiC,GAAG,UAAU,CAoCjG;AAED;uFACuF;AACvF,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG1E"}

package/dist/src/identity/backends/libsecret.d.ts

@@ -0,0 +1,4 @@
+import { type Exec } from './exec.js';
+import { type KeyBackend } from './types.js';
+export declare function createLibsecretBackend(exec?: Exec, accountName?: string, serviceName?: string): KeyBackend;
+//# sourceMappingURL=libsecret.d.ts.map

package/dist/src/identity/backends/libsecret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"libsecret.d.ts","sourceRoot":"","sources":["../../../../src/identity/backends/libsecret.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAY,MAAM,WAAW,CAAC;AAChD,OAAO,EAAgB,KAAK,UAAU,EAAiC,MAAM,YAAY,CAAC;AAY1F,wBAAgB,sBAAsB,CAAC,IAAI,GAAE,IAAe,EAAE,WAAW,GAAE,MAAqB,EAAE,WAAW,GAAE,MAAqB,GAAG,UAAU,CAiDhJ"}

package/dist/src/identity/backends/macos-keychain.d.ts

@@ -0,0 +1,4 @@
+import { type Exec } from './exec.js';
+import { type KeyBackend } from './types.js';
+export declare function createMacosKeychainBackend(exec?: Exec, accountName?: string, serviceName?: string): KeyBackend;
+//# sourceMappingURL=macos-keychain.d.ts.map

package/dist/src/identity/backends/macos-keychain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"macos-keychain.d.ts","sourceRoot":"","sources":["../../../../src/identity/backends/macos-keychain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,EAAY,MAAM,WAAW,CAAC;AAChD,OAAO,EAAgB,KAAK,UAAU,EAAiC,MAAM,YAAY,CAAC;AAgB1F,wBAAgB,0BAA0B,CAAC,IAAI,GAAE,IAAe,EAAE,WAAW,GAAE,MAAqB,EAAE,WAAW,GAAE,MAAqB,GAAG,UAAU,CA+CpJ"}

package/dist/src/identity/backends/select.d.ts

@@ -0,0 +1,16 @@
+import type { KeyBackend } from './types.js';
+/**
+ * Fixed, platform-derived priority order. The SAME list is used for reads and writes (store.ts): a new
+ * key is written to the first available candidate, and every candidate is swept in this order when
+ * looking for an existing one. `file-fallback` is always last and always available, so this list can
+ * never be empty and a caller can never end up with nowhere to store a key.
+ *
+ * CRITICAL: the agent's names (SERVICE_NAME / ACCOUNT_NAME) are FROZEN for backward compatibility.
+ * Existing installs already have keys stored under these names. Wallet uses a distinct ACCOUNT_NAME
+ * to prevent collision.
+ */
+export declare function defaultCandidates(platform?: NodeJS.Platform, isWallet?: boolean): KeyBackend[];
+/** Pick the first available backend from `candidates`, in order. Used only to decide where a NEW key
+ *  gets written - see the KeyBackend interface doc for why reads don't use this. */
+export declare function selectAvailable(candidates: KeyBackend[]): Promise<KeyBackend>;
+//# sourceMappingURL=select.d.ts.map