@dev.sail.money/sailor 1.2.0-74 → 1.2.0-76

package/README.md

@@ -62,7 +62,7 @@ The path from nothing to a running agent follows the protocol lifecycle:
 2. **Author your permissions** — describe what the agent may do. Permission contracts encode the bounds: tokens, amounts, venues, call targets. Author them in the scaffolded Foundry workspace.
 3. **Simulate, deploy, and sign your mandate** — `sailor mandate simulate` probes a permission off-chain before authorizing it. `sailor mandate deploy --attach` deploys and registers it on-chain. `sailor mandate sign` builds and signs the registration payload against live on-chain state.
 4. **Run** — `sailor run` executes the agent loop. Three execution hosts compose: run it locally on a schedule, install it as a local OS service (`sailor service install` — launchd/systemd/Task Scheduler) that restarts on crash, or let the GitHub Actions cron workflow the scaffold provides run it. `sailor trigger github` fires that workflow on demand.
-5. **Operate** — `sailor doctor` checks kernel health and gas balances; `sailor chains` lists supported chains and deployment addresses; `sailor session pause` instantly revokes dispatch rights without touching Safe custody.
+5. **Operate** — `sailor doctor` checks kernel health and gas balances; `sailor chains` lists supported chains and deployment addresses; `sailor session pause` instantly revokes dispatch rights without touching Safe custody. After a CLI upgrade, `sailor update` resyncs agent tooling files (skills, `AGENTS.md`, `Dockerfile`) without touching user code or runtime state.
 
 Run `npx sailor init my-agent`, open the scaffolded folder in Claude Code, Cursor, or any AI coding assistant, and say **"start"**.
 
@@ -158,6 +158,9 @@ sailor trigger github      # fire the agent's GitHub Actions workflow on demand
 
 # Dashboard
 sailor ui start            # prints the per-project dashboard URL
+
+# Maintenance
+sailor update              # re-sync skills, AGENTS.md, and tooling files after a CLI upgrade
 ```
 
 `sailor run` writes reverted transactions to stderr as `reverted: <txHash> (gas used: N)`; successful dispatches are appended to `.sail/activity.jsonl`.

package/examples/permissions/BoundedSwapNative_UniswapV3_Base.sol

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Protocol : Uniswap V3 — NATIVE-ASSET (ETH) swap
+// Version  : SwapRouter02 (NOT the older SwapRouter — different selectors)
+// Chain    : Base mainnet (8453)
+// Target   : SwapRouter02  0x2626664c2603336E57B271c5C0b26F421741e481  (verified on Basescan)
+//
+// WHY A SEPARATE EXAMPLE FOR NATIVE ETH:
+//   When the asset being spent is the chain's NATIVE asset (ETH), the value that actually
+//   leaves the account is the call's `msg.value` — exposed to the permission as `Context.value`
+//   (`ctx.value`) — NOT the calldata `amountIn`. SwapRouter02 swaps native ETH by wrapping the
+//   ETH you send (tokenIn = WETH in the calldata) into WETH inside the router. So a permission
+//   adapted naively from the ERC-20 swap example (BoundedSwap_UniswapV3_Base.sol) would bound
+//   `amountIn` while leaving `ctx.value` UNBOUNDED — and the on-chain bound would NOT cap the
+//   funds actually spent. That is the trap this example exists to close.
+//
+// THE RULE THIS EXAMPLE DEMONSTRATES:
+//   For ANY value-carrying call, `Context.value` MUST be explicitly bounded. Bounding the
+//   calldata amount is not enough — the real spend is `ctx.value`.
+//
+// ENFORCES ON-CHAIN (kernel calls evaluate() on every dispatch; false ⇒ dispatch blocked):
+//   exactInputSingle((address,address,uint24,address,uint256,uint256,uint160))  selector 0x04e45aaf
+//     • target must be SWAP_ROUTER
+//     • ctx.value ≤ MAX_AMOUNT_IN          ← bounds the REAL native spend
+//     • amountIn == ctx.value              ← forces the native path; no value/amount drift
+//     • tokenIn  must equal WETH           ← the router wraps ctx.value into WETH
+//     • tokenOut must be in ALLOWED_TOKENS_OUT
+//
+// AGENT-ENFORCED / NOT BOUNDED HERE (off-chain — can change without redeploying this contract):
+//   • fee tier, sqrtPriceLimitX96, recipient address
+//   • swap frequency / cadence
+//   • slippage — see the note below
+//
+// SLIPPAGE IS NOT BOUNDED ON-CHAIN HERE — AND CANNOT BE, without a price oracle:
+//   `amountOutMinimum` (output token) and `ctx.value`/`amountIn` (native ETH) are denominated in
+//   DIFFERENT tokens, so a ratio between them bounds nothing real (see BoundedSwap_UniswapV3_Base
+//   for the full explanation). Compute `amountOutMinimum` OFF-CHAIN from a live quote and pass it
+//   in per swap; the router reverts if the output falls below it. This contract only caps the
+//   native input spend (MAX_AMOUNT_IN).
+//
+// VERIFY BEFORE USE:
+//   • Confirm SwapRouter02 + WETH addresses on your chain (Base defaults shown; verify on-chain).
+//   • Native ETH swaps on SwapRouter02 are typically wrapped in a payable multicall (so the
+//     router can refundETH any unspent wei). This example bounds the single exactInputSingle
+//     leg; if your agent routes the swap through `multicall`, add a permission that decodes the
+//     multicall and applies these same ctx.value / amountIn checks to the inner call.
+//   • Selector 0x04e45aaf = exactInputSingle((address,address,uint24,address,uint256,uint256,uint160))
+//     on SwapRouter02 (verified via `cast sig`). The OLDER SwapRouter's exactInputSingle (the
+//     deadline variant) is 0x414bf389 — a different selector; do not confuse the two.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
+
+contract BoundedSwapNative_UniswapV3_Base is IPermission {
+    bytes32 private constant DISCRIMINATOR = keccak256("BoundedSwapNative_UniswapV3_Base");
+
+    address public immutable SWAP_ROUTER;
+    /// @dev The wrapped-native token (WETH). SwapRouter02 wraps the ETH sent as ctx.value
+    ///      into this token, so the calldata tokenIn for a native swap is WETH.
+    address public immutable WETH;
+    mapping(address => bool) public isAllowedTokenOut;
+    /// @dev Per-call cap on the native spend, in wei. Bounds ctx.value, the REAL spend.
+    uint256 public immutable MAX_AMOUNT_IN;
+
+    bytes4 private constant SEL_EXACT_INPUT_SINGLE = 0x04e45aaf;
+
+    struct ExactInputSingleParams {
+        address tokenIn;
+        address tokenOut;
+        uint24  fee;
+        address recipient;
+        uint256 amountIn;
+        uint256 amountOutMinimum;
+        uint160 sqrtPriceLimitX96;
+    }
+
+    /// @param swapRouter      SwapRouter02 address (0x2626... on Base)
+    /// @param weth            Wrapped-native token address (WETH on Base: 0x4200...0006)
+    /// @param allowedTokensOut  Tokens the agent may receive
+    /// @param maxAmountIn     Per-call native spend cap in wei (bounds ctx.value)
+    /// @dev No slippage parameter: slippage cannot be bounded on-chain without a price oracle
+    ///      (see the header note). Pass a tight `amountOutMinimum`, computed off-chain from a
+    ///      live quote, on each swap — the router enforces it by reverting.
+    constructor(
+        address swapRouter,
+        address weth,
+        address[] memory allowedTokensOut,
+        uint256 maxAmountIn
+    ) {
+        SWAP_ROUTER   = swapRouter;
+        WETH          = weth;
+        MAX_AMOUNT_IN = maxAmountIn;
+        for (uint256 i = 0; i < allowedTokensOut.length; i++) {
+            isAllowedTokenOut[allowedTokensOut[i]] = true;
+        }
+    }
+
+    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
+        if (txData.length < 4) return false;
+        if (ctx.target != SWAP_ROUTER || ctx.selector != SEL_EXACT_INPUT_SINGLE) return false;
+        if (txData.length < 4 + 7 * 32) return false;
+
+        ExactInputSingleParams memory p = abi.decode(txData[4:], (ExactInputSingleParams));
+
+        // Bound the REAL native spend. ctx.value is the ETH actually leaving the account;
+        // bounding amountIn alone would leave the spend uncapped.
+        if (ctx.value > MAX_AMOUNT_IN) return false;
+        // No drift between the declared amount and the native value sent — a native swap pays
+        // entirely with ctx.value, so amountIn must equal it exactly.
+        if (p.amountIn != ctx.value)  return false;
+
+        // tokenIn is WETH: the router wraps ctx.value into WETH before swapping.
+        if (p.tokenIn != WETH)              return false;
+        if (!isAllowedTokenOut[p.tokenOut]) return false;
+        // amountOutMinimum intentionally not checked — see header (slippage cannot be bounded
+        // on-chain; the router enforces the off-chain-computed value the agent passes in).
+        return true;
+    }
+
+    function discriminator() external pure returns (bytes32) { return DISCRIMINATOR; }
+}

package/examples/permissions/BoundedSwap_UniswapV3_Base.sol

@@ -13,7 +13,6 @@ pragma solidity 0.8.26;
 //     • tokenIn  must equal FIXED_TOKEN_IN
 //     • tokenOut must be in ALLOWED_TOKENS_OUT
 //     • amountIn ≤ MAX_AMOUNT_IN
-//     • amountOutMinimum ≥ amountIn × MIN_BPS / 10 000  (slippage floor — see caveat below)
 //   approve(address,uint256)  selector 0x095ea7b3
 //     • target must be FIXED_TOKEN_IN (the ERC-20 being approved)
 //     • spender must be SWAP_ROUTER
@@ -22,15 +21,24 @@ pragma solidity 0.8.26;
 // AGENT-ENFORCED / NOT BOUNDED HERE (off-chain — can change without redeploying this contract):
 //   • fee tier, sqrtPriceLimitX96, recipient address
 //   • swap frequency / cadence
-//   • real (cross-denomination) slippage — see MIN_BPS caveat in evaluate()
+//   • slippage — see the note below
+//
+// SLIPPAGE IS NOT BOUNDED ON-CHAIN HERE — AND CANNOT BE, without a price oracle:
+//   `amountOutMinimum` (output token) and `amountIn` (input token) are denominated in DIFFERENT
+//   tokens. Comparing them as a ratio — the pattern an earlier version of this example shipped —
+//   is meaningless for any pair whose tokens differ in price or decimals (e.g. USDC→WETH): the
+//   check is either trivially satisfied or trivially failed, giving false confidence while
+//   protecting nothing. So this permission deliberately does NOT constrain `amountOutMinimum`.
+//   Real slippage protection must be computed OFF-CHAIN from a live quote (e.g. the Quoter or a
+//   price feed) and passed in as `amountOutMinimum` on each swap — the router reverts if the
+//   output falls below it. Your agent owns choosing a tight, fresh value per call; this contract
+//   only caps the input spend (MAX_AMOUNT_IN).
 //
 // VERIFY BEFORE USE:
 //   • Confirm SwapRouter02 address on your chain (Base default shown above; verified on Basescan).
 //   • Selector 0x04e45aaf = exactInputSingle((address,address,uint24,address,uint256,uint256,uint160))
 //     on SwapRouter02 (verified via `cast sig`). The OLDER SwapRouter's exactInputSingle (the
 //     deadline variant) is 0x414bf389 — a different selector; do not confuse the two.
-//   • Confirm that amountOutMinimum slippage floor fits your price-impact expectations for the
-//     chosen pool. Large amountIn values may trigger price impact beyond MIN_BPS.
 // ─────────────────────────────────────────────────────────────────────────────
 
 import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
@@ -42,8 +50,6 @@ contract BoundedSwap_UniswapV3_Base is IPermission {
     address public immutable FIXED_TOKEN_IN;
     mapping(address => bool) public isAllowedTokenOut;
     uint256 public immutable MAX_AMOUNT_IN;
-    /// @dev Slippage floor in basis points. 9 900 = allow at most 1% slippage.
-    uint256 public immutable MIN_BPS;
 
     bytes4 private constant SEL_EXACT_INPUT_SINGLE = 0x04e45aaf;
     bytes4 private constant SEL_APPROVE            = 0x095ea7b3;
@@ -62,21 +68,18 @@ contract BoundedSwap_UniswapV3_Base is IPermission {
     /// @param fixedTokenIn    The one token the agent is allowed to sell
     /// @param allowedTokensOut  Tokens the agent may receive
     /// @param maxAmountIn     Per-call spend cap in fixedTokenIn base units
-    /// @param minBps          Minimum amountOutMinimum as fraction of amountIn ×10 000
-    ///                        e.g. 9900 → require amountOutMinimum ≥ 99% of amountIn
-    ///                        (denominated in fixedTokenIn units, not USD — set per your pair)
+    /// @dev No slippage parameter: slippage cannot be bounded on-chain without a price oracle
+    ///      (see the header note). Pass a tight `amountOutMinimum`, computed off-chain from a
+    ///      live quote, on each swap — the router enforces it by reverting.
     constructor(
         address swapRouter,
         address fixedTokenIn,
         address[] memory allowedTokensOut,
-        uint256 maxAmountIn,
-        uint256 minBps
+        uint256 maxAmountIn
     ) {
-        require(minBps <= 10_000, "minBps > 10000");
         SWAP_ROUTER    = swapRouter;
         FIXED_TOKEN_IN = fixedTokenIn;
         MAX_AMOUNT_IN  = maxAmountIn;
-        MIN_BPS        = minBps;
         for (uint256 i = 0; i < allowedTokensOut.length; i++) {
             isAllowedTokenOut[allowedTokensOut[i]] = true;
         }
@@ -92,11 +95,10 @@ contract BoundedSwap_UniswapV3_Base is IPermission {
             if (p.tokenIn != FIXED_TOKEN_IN)         return false;
             if (!isAllowedTokenOut[p.tokenOut])      return false;
             if (p.amountIn > MAX_AMOUNT_IN)          return false;
-            // Slippage floor: amountOutMinimum ≥ amountIn × MIN_BPS / 10 000.
-            // WARNING: compares tokenOut against tokenIn base units. For same-price/same-decimal
-            // pairs this maps to a slippage %. For cross-price pairs (e.g. USDC→WETH) it is
-            // trivially satisfied — real slippage is enforced by the agent off-chain, not here.
-            if (p.amountOutMinimum < (p.amountIn * MIN_BPS) / 10_000) return false;
+            // amountOutMinimum is intentionally NOT checked here — it is denominated in the
+            // output token, so a ratio against amountIn (input token) bounds nothing real for a
+            // cross-price pair (see header). The router enforces the off-chain-computed
+            // amountOutMinimum the agent passes in.
             return true;
         }
 

package/examples/permissions/BoundedSwap_UniswapV4_Unichain.sol

@@ -19,12 +19,19 @@ pragma solidity 0.8.26;
 //     • tokenIn (from poolKey, derived by zeroForOne) must be FIXED_CURRENCY_IN
 //     • tokenOut must be in ALLOWED_CURRENCIES_OUT
 //     • amountIn ≤ MAX_AMOUNT_IN
-//     • amountOutMinimum ≥ amountIn × MIN_BPS / 10 000  (slippage floor — see caveat below)
 //
 // AGENT-ENFORCED / NOT BOUNDED HERE (off-chain — can change without redeploying this contract):
-//   • real (cross-denomination) slippage — see MIN_BPS caveat in evaluate()
+//   • slippage — see the note below
 //   • swap frequency / cadence
 //
+// SLIPPAGE IS NOT BOUNDED ON-CHAIN HERE — AND CANNOT BE, without a price oracle:
+//   `amountOutMinimum` (output currency) and `amountIn` (input currency) are denominated in
+//   DIFFERENT tokens. A ratio between them — the pattern an earlier version of this example
+//   shipped — bounds nothing real for any pair whose tokens differ in price or decimals. So this
+//   permission deliberately does NOT constrain `amountOutMinimum`. Compute it OFF-CHAIN from a
+//   live quote and pass it in per swap; the router reverts if the output falls below it. This
+//   contract only caps the input spend (MAX_AMOUNT_IN).
+//
 // DOCUMENTED LIMITATIONS (on-chain, but intentionally not constrained):
 //   • hookData is not inspected (hooks can alter swap behavior on-chain; if the
 //     pool uses a hook that significantly changes execution, this permission cannot
@@ -54,7 +61,6 @@ contract BoundedSwap_UniswapV4_Unichain is IPermission {
     address public immutable FIXED_CURRENCY_IN;
     mapping(address => bool) public isAllowedCurrencyOut;
     uint256 public immutable MAX_AMOUNT_IN;
-    uint256 public immutable MIN_BPS;
 
     // execute(bytes,bytes[],uint256) — with deadline
     bytes4 private constant SEL_EXECUTE_DEADLINE = 0x3593564c;
@@ -84,18 +90,18 @@ contract BoundedSwap_UniswapV4_Unichain is IPermission {
         bytes   hookData;   // not inspected — see limitations header
     }
 
+    /// @dev No slippage parameter: slippage cannot be bounded on-chain without a price oracle
+    ///      (see the header note). Pass a tight `amountOutMinimum`, computed off-chain from a
+    ///      live quote, on each swap — the router enforces it by reverting.
     constructor(
         address universalRouter,
         address fixedCurrencyIn,
         address[] memory allowedCurrenciesOut,
-        uint256 maxAmountIn,
-        uint256 minBps
+        uint256 maxAmountIn
     ) {
-        require(minBps <= 10_000, "minBps > 10000");
         UNIVERSAL_ROUTER  = universalRouter;
         FIXED_CURRENCY_IN = fixedCurrencyIn;
         MAX_AMOUNT_IN     = maxAmountIn;
-        MIN_BPS           = minBps;
         for (uint256 i = 0; i < allowedCurrenciesOut.length; i++) {
             isAllowedCurrencyOut[allowedCurrenciesOut[i]] = true;
         }
@@ -137,11 +143,10 @@ contract BoundedSwap_UniswapV4_Unichain is IPermission {
         if (tokenIn != FIXED_CURRENCY_IN)            return false;
         if (!isAllowedCurrencyOut[tokenOut])         return false;
         if (p.amountIn > MAX_AMOUNT_IN)              return false;
-        // Slippage floor: amountOutMinimum ≥ amountIn × MIN_BPS / 10 000.
-        // WARNING: compares tokenOut against tokenIn base units. For same-price/same-decimal
-        // pairs this maps to a slippage %. For cross-price pairs it is trivially satisfied —
-        // real slippage is enforced by the agent off-chain, not by this contract.
-        if (p.amountOutMinimum < (uint256(p.amountIn) * MIN_BPS) / 10_000) return false;
+        // amountOutMinimum is intentionally NOT checked — it is denominated in the output
+        // currency, so a ratio against amountIn (input currency) bounds nothing real for a
+        // cross-price pair (see header). The router enforces the off-chain-computed
+        // amountOutMinimum the agent passes in.
 
         return true;
     }

package/examples/permissions/README.md

@@ -23,6 +23,15 @@ against the protocol's real ABI, and confirm what it enforces before deploying.
 
 You own what you deploy.
 
+## Bound `Context.value` on every value-carrying call
+
+For any call that can carry native asset (ETH), the value actually leaving the account is the
+call's `msg.value` — exposed to your permission as `Context.value` (`ctx.value`) — **not** the
+calldata amount. A permission that bounds only a calldata `amount`/`amountIn` leaves the real
+spend uncapped. So: **every value-carrying call must explicitly bound `Context.value`**, and where
+the calldata also declares an amount, assert `amount == ctx.value` so the two cannot drift. See
+`BoundedSwapNative_UniswapV3_Base.sol` for the worked native-ETH example.
+
 ---
 
 ## Examples
@@ -35,6 +44,7 @@ off-chain agent code — these do *not* hold on-chain). Read both before deployi
 |---|---|---|---|---|
 | `BoundedSwap_UniswapV3_Base.sol` | Uniswap Swap | V3 SwapRouter02 | Base | Full decode |
 | `BoundedSwap_UniswapV4_Unichain.sol` | Uniswap Swap | V4 Universal Router | Unichain | Partial decode — see header |
+| `BoundedSwapNative_UniswapV3_Base.sol` | Uniswap Swap (native ETH) | V3 SwapRouter02 | Base | Full decode — bounds `Context.value` (native spend) |
 | `BoundedBorrow_AaveV3_Arbitrum.sol` | Aave Borrow | V3 Pool | Arbitrum | Full decode |
 | `BoundedSupply_AaveV3_Arbitrum.sol` | Aave Supply | V3 Pool | Arbitrum | Full decode |
 | `BoundedVault_ERC4626_Base.sol` | ERC-4626 Vault deposit/withdraw | EIP-4626 standard | Base (any EVM) | Full decode |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev.sail.money/sailor",
-  "version": "1.2.0-74",
+  "version": "1.2.0-76",
   "description": "Operator toolkit for Sail Protocol",
   "bin": {
     "sailor": "packages/cli/dist/index.cjs"