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

package/templates/default/.agents/skills/sail-mandates/references/examples-index.md

@@ -6,8 +6,9 @@ Permissions only bound on-chain actions: venues with off-chain order matching (P
 
 | File | Protocol / chain | Teaches | Key verified selectors |
 |---|---|---|---|
-| `BoundedSwap_UniswapV3_Base.sol` | Uniswap V3 SwapRouter02 · Base | Selector allowlist + amount cap + tokenOut allowlist + min-out slippage floor (MIN_BPS) | `0x04e45aaf` exactInputSingle (SwapRouter02), `0x095ea7b3` approve |
-| `BoundedSwap_UniswapV4_Unichain.sol` | Uniswap V4 Universal Router · Unichain | Decoding command/action bytes: single V4_SWAP command, single SWAP_EXACT_IN_SINGLE action, currency + amount + slippage bounds | `0x3593564c` execute(bytes,bytes[],uint256), `0x24856bc3` execute(bytes,bytes[]) |
+| `BoundedSwap_UniswapV3_Base.sol` | Uniswap V3 SwapRouter02 · Base | Selector allowlist + input-spend cap + tokenOut allowlist; teaches why slippage CANNOT be bounded on-chain (amountOutMinimum is a different token than amountIn — pass an off-chain-quoted value) | `0x04e45aaf` exactInputSingle (SwapRouter02), `0x095ea7b3` approve |
+| `BoundedSwap_UniswapV4_Unichain.sol` | Uniswap V4 Universal Router · Unichain | Decoding command/action bytes: single V4_SWAP command, single SWAP_EXACT_IN_SINGLE action, currency + input-spend bounds; same slippage caveat as the V3 example | `0x3593564c` execute(bytes,bytes[],uint256), `0x24856bc3` execute(bytes,bytes[]) |
+| `BoundedSwapNative_UniswapV3_Base.sol` | Uniswap V3 SwapRouter02 (native ETH) · Base | Native-asset spend: bound `ctx.value` (the real spend) + assert `amountIn == ctx.value`; tokenIn = WETH (router wraps the sent ETH). The canonical "bound Context.value" example | `0x04e45aaf` exactInputSingle (SwapRouter02) |
 | `BoundedBorrow_AaveV3_Arbitrum.sol` | Aave V3 Pool · Arbitrum | Asset allowlist + borrow cap + `onBehalfOf == ctx.account` binding + rate-mode allowlist (use [2]; stable deprecated in V3.1) | `0xa415bcad` borrow(address,uint256,uint256,uint16,address) |
 | `BoundedSupply_AaveV3_Arbitrum.sol` | Aave V3 Pool · Arbitrum | SailCalldata-based decoding; supply cap + `onBehalfOf == ctx.account`; supply does NOT gate withdrawal, and the prior approve needs its own permission | `0x617ba037` supply(address,uint256,address,uint16) |
 | `BoundedVault_ERC4626_Base.sol` | ERC-4626 standard · any EVM | Vault allowlist; deposit capped + receiver bound; withdraw/redeem receiver+owner bound but amount-unbounded (SMA can always fully exit) | `0x6e553f65` deposit, `0xb460af94` withdraw, `0xba087652` redeem |
@@ -19,6 +20,8 @@ Permissions only bound on-chain actions: venues with off-chain order matching (P
 
 ## Lessons the examples encode
 
+- **Value-carrying calls — bound `Context.value`, always.** For any call that can carry native asset, the value actually leaving the account is `ctx.value` (`msg.value`), NOT the calldata amount. A permission that bounds only a calldata `amount`/`amountIn` leaves the real spend uncapped. Rule: **every value-carrying call must explicitly bound `Context.value`** — and where the calldata declares its own amount, also assert `amount == ctx.value` so the two can't drift. `BoundedSwapNative_UniswapV3_Base.sol` is the worked native-ETH example; the ERC-20 `BoundedSwap_UniswapV3_Base.sol` carries no value, so it bounds `amountIn` only. When in doubt, add `if (ctx.value > MAX) return false;`.
+- **Slippage can't be bounded on-chain without a price oracle.** `amountOutMinimum` (output token) and `amountIn`/`ctx.value` (input token) are different denominations — a ratio between them is meaningless for any cross-price pair (USDC→WETH), giving false confidence while protecting nothing. The swap examples deliberately do NOT constrain `amountOutMinimum`; the agent computes it off-chain from a live quote and the router enforces it by reverting. Bound the input spend on-chain; bound the output off-chain.
 - **Venice — the wrong-selector bug.** The live contract's function is `stake(address,uint256)` = `0xadc9772e`. The intuitive single-arg `stake(uint256)` = `0xa694fc3a` does not exist on the target. Gating the wrong selector fails closed: every legitimate stake silently rejected. Always confirm the selector against the deployed contract.
 - **GMX — versioned ABIs drift.** GMX has multiple ExchangeRouter deployments and the `CreateOrderParams` struct has gained fields over time. Before deploying: pick the exact router the agent calls, read its verified ABI, recompute with `cast sig "createOrder(<exact tuple>)"`, and update the selector and struct if they differ. The committed `0x212234c3` is verified against gmx-io/gmx-synthetics at time of writing — re-verify anyway.
 - **Limitless — unverified ABI as a worked warning.** The exchange address and `buy` signature are inferred from CTF patterns, not verified against the deployed contract. The contract's own header lists the verification steps; do them before any deploy.

package/templates/default/.agents/skills/sail-onboarding/SKILL.md

@@ -9,6 +9,8 @@ description: Walks the agent through setting up a new Sailor project or resuming
 
 The project does not install `sailor` as a dependency, so invoke it with **`npx sailor <command>`** unless it is installed globally (`npm i -g @sail.money/sailor`, then `sailor` works bare). Every `sailor …` command in these skills assumes one of those. Confirm the toolchain up front and pin a recent version — `npx sailor@latest --version` — because an old cached `npx` build can be missing newer commands (e.g. `mandate simulate`); if a documented command reports "unknown command", you are on a stale version, not hitting a missing feature.
 
+After upgrading the CLI, run `sailor update` from the project root to pull in updated skills, `AGENTS.md`, `Dockerfile`, and other tooling files. User files (`src/`, `mandates/`, `.sail/`, `package.json`) are never touched.
+
 Stage machine keyed off `.sail/`. Read the state, enter at the right stage, never re-run completed stages.
 
 ## Determine where the user is

package/templates/default/AGENTS.md

@@ -64,7 +64,7 @@ Detailed procedures live in skills. If your tooling does not auto-discover skill
 | sail-servers | Starting, stopping, or health-checking the dashboard or signing station | `.agents/skills/sail-servers/SKILL.md` |
 | sail-transactions | Building dispatches or any EVM transaction for the agent | `.agents/skills/sail-transactions/SKILL.md` |
 | sail-mandates | Designing, authoring, testing, deploying, or authorizing permission contracts | `.agents/skills/sail-mandates/SKILL.md` |
-| sail-ci | Automating the agent on a schedule via GitHub Actions | `.agents/skills/sail-ci/SKILL.md` |
+| sail-automation | Automating the agent — GitHub Actions, self-hosted runner, Docker, or local daemon | `.agents/skills/sail-automation/SKILL.md` |
 | sail-extend | Notifications or a custom dashboard, once the agent is live | `.agents/skills/sail-extend/SKILL.md` |
 
 ## Invariants — apply to every turn

package/templates/default/Dockerfile

@@ -0,0 +1,18 @@
+FROM node:20-slim
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm install
+
+COPY . .
+
+# Seconds between runs. Tune to your strategy: 60 = per-minute, 300 = 5 min, 86400 = daily.
+ENV AGENT_INTERVAL=300
+
+CMD ["sh", "-c", "\
+  mkdir -p .sail/keys && \
+  cp ci-keystore.json .sail/keys/manager.json && \
+  while true; do \
+    npx sailor run --once; \
+    sleep ${AGENT_INTERVAL}; \
+  done"]

package/templates/default/_dockerignore

@@ -0,0 +1,15 @@
+# Secrets and local state — never bake into the image.
+.sail/keys/
+.sail/runtime/
+.sail/state/
+.sail/.env.local
+.env
+.env.*
+!.env.example
+
+# Build outputs
+node_modules/
+out/
+cache/
+broadcast/
+dist/

package/templates/default/.agents/skills/sail-ci/SKILL.md

@@ -1,63 +0,0 @@
----
-name: sail-ci
-description: Run the agent unattended — cloud (GitHub Actions cron + workflow_dispatch), a local OS service (sailor service install), or on-demand via the trigger seam (sailor trigger github) — with cadence guidance and the committed-keystore trust model. Use after sailor run --once works.
----
-
-# Sail CI — automating the agent
-
-Confirm `sailor run --once` works first. Three hosts run the same loop; pick by latency, privacy, and ops:
-
-- **Cloud** — GitHub Actions cron + `workflow_dispatch`. Zero infra; cron drifts (see Cadence).
-- **Local daemon** — `sailor service install`. Private, no committed keys, lower latency, no GitHub — you run the host.
-- **Event-driven** — an external system fires a run via the trigger seam (a keeper/watcher on a price move or deposit). The direction, not yet built; today the seam is `sailor trigger github`.
-
-## Cadence
-
-Match the interval to volatility: **LP / perp → minutes; DCA / rebalance → daily; treasury → hourly–daily.** Actions cron is a *heartbeat/backstop* that drifts and skips under load — not low-latency; for that, use an external trigger or the local daemon.
-
-## Cloud: GitHub Actions
-
-`.github/workflows/agent-tick.yml` runs `npx sailor run --once` on cron (default hourly `0 * * * *`, a generic placeholder — tune `cron` to your strategy per Cadence above; `workflow_dispatch` enables manual/external runs), via `npm ci`. `CHAIN_ID` comes from the repo variable (default `8453`).
-
-1. **Export** — `sailor keys export-ci` writes the geth-v3 encrypted `ci-keystore.json` (raw key never exposed) and allowlists it in `.gitignore`.
-2. **Commit** the non-secret files (`npm install` first for the lockfile):
-
-```bash
-git add ci-keystore.json package-lock.json .sail/account.json .sail/config.json .sail/mandate.json
-git commit -m "chore: add CI keystore and sail state" && git push
-```
-
-3. **Secrets** (Settings → Secrets and variables → Actions): `SAIL_PASSPHRASE`, `RPC_URL`. If not Base, set the repo **variable** `CHAIN_ID`.
-4. **Drive with `gh`** (needs the `workflow` scope — `gh auth login --scopes workflow`):
-
-```bash
-gh secret set SAIL_PASSPHRASE && gh secret set RPC_URL
-gh workflow run agent-tick.yml          # manual run
-gh run list --workflow agent-tick.yml   # history
-gh run view --log                       # latest logs
-```
-
-## On-demand / external trigger
-
-```bash
-sailor trigger github                   # fire workflow_dispatch — the same job cron runs
-#   --reason <text>  --ref <branch>  --workflow <file>  --repo <owner/repo>  --json
-```
-
-Wakes the agent between cron ticks — the seam keepers, watchers, or your backend call.
-
-## Local daemon
-
-```bash
-sailor service install --interval 300   # launchd/systemd/Task Scheduler; restarts on crash
-sailor service status | stop | uninstall
-sailor service logs -f                  # .sail/agent.log
-```
-
-`--project`/`--chain` scope it; `--force` overrides a TCC path or unresolved passphrase.
-
-## Keys & trust
-
-Cloud commits only the **encrypted** keystore; `SAIL_PASSPHRASE` is a secret, never committed (the same value the dashboard stores locally at `0600`). Whoever triggers or submits, the on-chain **mandate is the backstop**, bounding the manager regardless of host — choose cloud vs local with that in mind.
-
-A failing run's logs show the same stderr as the local runner (`reverted: <txHash>`, `skipped: no registered permission…`) — debug with the sail-transactions skill.