@dev.sail.money/sailor 0.0.2-12 → 0.0.2-13

package/templates/default/examples/dca/agent.ts

@@ -0,0 +1,174 @@
+// Reference example — not the user's strategy. Consult for patterns; author the user's own in src/.
+// Shows: a complete DCA tick loop — USDC→WETH via Uniswap V3 on Base mainnet.
+// To adapt: replace token addresses, protocol ABIs, and swap logic with your target strategy.
+
+import type { Agent, AgentContext, Call, Dispatch } from "@sail/sdk";
+import { encodeFunctionData, type PublicClient } from "viem";
+import {
+  ALLOWED_TOKENS,
+  MIN_USDC_TO_SWAP,
+  QUOTER_V2,
+  SLIPPAGE_BPS,
+  SWAP_AMOUNT_USDC,
+  SWAP_FEE_TIER,
+  SWAP_ROUTER,
+} from "./mandate.js";
+
+// ── ABI fragments ─────────────────────────────────────────────────────────────
+
+const ERC20_ABI = [
+  {
+    name: "allowance",
+    type: "function",
+    stateMutability: "view",
+    inputs: [
+      { name: "owner", type: "address" },
+      { name: "spender", type: "address" },
+    ],
+    outputs: [{ type: "uint256" }],
+  },
+  {
+    name: "approve",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "spender", type: "address" },
+      { name: "amount", type: "uint256" },
+    ],
+    outputs: [{ type: "bool" }],
+  },
+] as const;
+
+const QUOTER_V2_ABI = [
+  {
+    name: "quoteExactInputSingle",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      {
+        name: "params",
+        type: "tuple",
+        components: [
+          { name: "tokenIn", type: "address" },
+          { name: "tokenOut", type: "address" },
+          { name: "amountIn", type: "uint256" },
+          { name: "fee", type: "uint24" },
+          { name: "sqrtPriceLimitX96", type: "uint160" },
+        ],
+      },
+    ],
+    outputs: [
+      { name: "amountOut", type: "uint256" },
+      { name: "sqrtPriceX96After", type: "uint160" },
+      { name: "initializedTicksCrossed", type: "uint32" },
+      { name: "gasEstimate", type: "uint256" },
+    ],
+  },
+] as const;
+
+const SWAP_ROUTER_ABI = [
+  {
+    name: "exactInputSingle",
+    type: "function",
+    stateMutability: "payable",
+    inputs: [
+      {
+        name: "params",
+        type: "tuple",
+        components: [
+          { name: "tokenIn", type: "address" },
+          { name: "tokenOut", type: "address" },
+          { name: "fee", type: "uint24" },
+          { name: "recipient", type: "address" },
+          { name: "amountIn", type: "uint256" },
+          { name: "amountOutMinimum", type: "uint256" },
+          { name: "sqrtPriceLimitX96", type: "uint160" },
+        ],
+      },
+    ],
+    outputs: [{ name: "amountOut", type: "uint256" }],
+  },
+] as const;
+
+// ── Intent builder ────────────────────────────────────────────────────────────
+
+function intent(call: Call): Dispatch {
+  return { txHash: "0x", calls: [call], success: false, gasUsed: 0n };
+}
+
+// ── Agent ─────────────────────────────────────────────────────────────────────
+
+export const agent: Agent = {
+  name: "dca-rebalancer",
+  description: `DCA into WETH with USDC on Base via Uniswap V3. Slippage tolerance: ${SLIPPAGE_BPS / 100}%.`,
+
+  async tick(ctx: AgentContext): Promise<Dispatch[]> {
+    const { safe } = ctx;
+    ctx.log(`tick — block ${ctx.blockNumber}, sma ${safe}`);
+
+    const pc = ctx.data._publicClient as PublicClient | undefined;
+    if (!pc) {
+      ctx.log("no publicClient in ctx.data — skipping tick");
+      return [];
+    }
+
+    const usdc = ALLOWED_TOKENS[0]!;
+    const weth = ALLOWED_TOKENS[1]!;
+
+    // Step 1: Check USDC balance
+    const usdcBalance = await ctx.read.balance(usdc);
+    ctx.log(`USDC balance: ${usdcBalance} (min to swap: ${MIN_USDC_TO_SWAP})`);
+    if (usdcBalance < MIN_USDC_TO_SWAP) {
+      ctx.log("USDC balance below minimum — skipping tick");
+      return [];
+    }
+
+    // Step 2: Check allowance — approve first if needed
+    const allowance = await pc.readContract({
+      address: usdc,
+      abi: ERC20_ABI,
+      functionName: "allowance",
+      args: [safe, SWAP_ROUTER],
+    });
+    if (allowance < SWAP_AMOUNT_USDC) {
+      ctx.log(`allowance (${allowance}) < swap amount — submitting approve`);
+      return [intent({
+        target: usdc,
+        value: 0n,
+        data: encodeFunctionData({ abi: ERC20_ABI, functionName: "approve", args: [SWAP_ROUTER, 2n ** 256n - 1n] }),
+      })];
+    }
+
+    // Step 3: Quote via QuoterV2 — fail closed on any error
+    let expectedOut: bigint;
+    try {
+      const result = await pc.simulateContract({
+        address: QUOTER_V2,
+        abi: QUOTER_V2_ABI,
+        functionName: "quoteExactInputSingle",
+        args: [{ tokenIn: usdc, tokenOut: weth, amountIn: SWAP_AMOUNT_USDC, fee: SWAP_FEE_TIER, sqrtPriceLimitX96: 0n }],
+      });
+      expectedOut = (result.result as [bigint, bigint, number, bigint])[0];
+    } catch (e) {
+      ctx.log(`QuoterV2 unavailable: ${(e as Error).message.slice(0, 100)} — skipping`);
+      return [];
+    }
+    if (expectedOut === 0n) {
+      ctx.log("QuoterV2 returned 0 — skipping");
+      return [];
+    }
+
+    // Step 4: Encode swap with slippage protection
+    const minOut = (expectedOut * BigInt(10_000 - SLIPPAGE_BPS)) / 10_000n;
+    ctx.log(`quote: ${expectedOut} wei WETH, minOut (${SLIPPAGE_BPS / 100}% slippage): ${minOut}`);
+    return [intent({
+      target: SWAP_ROUTER,
+      value: 0n,
+      data: encodeFunctionData({
+        abi: SWAP_ROUTER_ABI,
+        functionName: "exactInputSingle",
+        args: [{ tokenIn: usdc, tokenOut: weth, fee: SWAP_FEE_TIER, recipient: safe, amountIn: SWAP_AMOUNT_USDC, amountOutMinimum: minOut, sqrtPriceLimitX96: 0n }],
+      }),
+    })];
+  },
+};

package/templates/{dca-rebalancer/src → default/examples/dca}/mandate.ts

@@ -1,3 +1,6 @@
+// Reference example — not the user's strategy. Consult for patterns; author the user's own in src/.
+// Shows: token addresses, swap parameters, and contract addresses for a USDC→WETH DCA on Base mainnet.
+
 import type { Address } from "@sail/sdk";
 
 // ── Token addresses (Base mainnet) ────────────────────────────────────────────
@@ -14,38 +17,18 @@ export const ALLOWED_TOKENS: Address[] = [
 
 // ── Swap parameters ───────────────────────────────────────────────────────────
 
-/**
- * Amount of USDC to spend per swap (in USDC base units, 6 decimals).
- * Default: 5 USDC. Adjust before deploying to production.
- */
+/** Amount of USDC to spend per swap (in USDC base units, 6 decimals). Default: 5 USDC. */
 export const SWAP_AMOUNT_USDC = 5_000_000n; // 5 USDC
 
-/**
- * Minimum USDC balance the SMA must hold before a swap is attempted.
- * Must be ≥ SWAP_AMOUNT_USDC. Adds a safety margin so a single swap
- * doesn't drain the account to zero.
- */
+/** Minimum USDC balance the SMA must hold before a swap is attempted. */
 export const MIN_USDC_TO_SWAP = 6_000_000n; // 6 USDC
 
-/**
- * Slippage tolerance in basis points (100 = 1%).
- * amountOutMinimum = quote × (1 − SLIPPAGE_BPS / 10 000).
- * If no quote is available, the agent skips the swap entirely (fail closed).
- *
- * Tighten for large trades or illiquid pairs; loosen if valid swaps are
- * frequently denied by price impact. Default 1% is conservative for
- * USDC/WETH on Base.
- */
+/** Slippage tolerance in basis points (100 = 1%). */
 export const SLIPPAGE_BPS = 100; // 1%
 
-/**
- * Uniswap V3 pool fee tier for the USDC/WETH pool on Base.
- * 500 = 0.05% — the most liquid USDC/WETH pool on Base mainnet.
- */
+/** Uniswap V3 pool fee tier for the USDC/WETH pool on Base (500 = 0.05%). */
 export const SWAP_FEE_TIER = 500;
 
-// ── Rebalancing ───────────────────────────────────────────────────────────────
-
 /** Rebalance when allocation drift exceeds this fraction (0.05 = 5%). */
 export const REBALANCE_THRESHOLD = 0.05;
 
@@ -57,11 +40,6 @@ export const SWAP_ROUTER: Address = "0x2626664c2603336E57B271c5C0b26F421741e481"
 /**
  * Uniswap V3 QuoterV2 on Base.
  * Called off-chain (via eth_call) to obtain the expected output amount
- * before computing amountOutMinimum. If this call fails, the agent skips
- * the swap — it never submits with amountOutMinimum = 0.
- *
- * Note: amountOutMinimum is set by the agent from the QuoterV2 result.
- * For defense-in-depth, add an on-chain minimum check in your permission
- * contract so the kernel also validates the minimum out requirement.
+ * before computing amountOutMinimum.
  */
 export const QUOTER_V2: Address = "0x3d4e44Eb1374240CE5F1B871ab261CD16335B76a";

package/templates/{dca-rebalancer → default}/package.json

@@ -1,7 +1,7 @@
 {
-  "name": "dca-rebalancer",
+  "name": "sail-agent",
   "version": "0.1.0",
-  "description": "Dollar-cost-average rebalancer — starter Sail Protocol agent",
+  "description": "Sail Protocol agent starter",
   "type": "module",
   "scripts": {
     "typecheck": "tsc -p tsconfig.json --noEmit"

package/templates/default/src/agent.ts

@@ -0,0 +1,37 @@
+/**
+ * Your agent — implement your strategy here.
+ *
+ * The runner calls tick() on every interval. Return an array of Dispatch intents;
+ * the runner submits each one through the kernel against a matching registered permission.
+ * Return [] to skip this tick (no gas spent).
+ *
+ * The runner resolves which permission authorizes each call automatically — you
+ * express what you want to do; you do not name permissions per call.
+ *
+ * For a worked end-to-end example (DCA / Uniswap V3 / Base):
+ *   see examples/dca/agent.ts and examples/dca/mandate.ts
+ */
+
+import type { Agent, AgentContext, Dispatch } from "@sail/sdk";
+
+export const agent: Agent = {
+  name: "my-agent",
+  description: "Describe your strategy here.",
+
+  async tick(ctx: AgentContext): Promise<Dispatch[]> {
+    ctx.log(`tick — block ${ctx.blockNumber}, sma ${ctx.safe}`);
+
+    // TODO: implement your strategy.
+    // Read on-chain state, decide what to do, return intent dispatches.
+    // ctx.read.balance(tokenAddress) — read token balance of the SMA
+    // ctx.data._publicClient — viem PublicClient for arbitrary on-chain reads
+    // ctx.log(msg) — append a message to the activity log
+    //
+    // Example (from examples/dca/agent.ts):
+    //   const balance = await ctx.read.balance(USDC_ADDRESS);
+    //   if (balance < MIN_AMOUNT) return [];
+    //   return [{ txHash: "0x", calls: [{ target: ROUTER, value: 0n, data: swapCalldata }], success: false, gasUsed: 0n }];
+
+    return [];
+  },
+};

package/templates/{dca-rebalancer → default}/src/config.ts

@@ -11,7 +11,14 @@ export function getEnvConfig(): { rpcUrl: string; chainId: number } {
     );
   }
 
-  const chainId = Number(process.env["CHAIN_ID"] ?? "8453"); // Default: Base mainnet
+  if (!process.env["CHAIN_ID"]) {
+    throw new Error(
+      "CHAIN_ID is not set.\n" +
+        "Open this folder in your AI coding assistant and say 'start' — Stage 1 will ask\n" +
+        "which chain you want and set CHAIN_ID in .sail/.env.local.",
+    );
+  }
+  const chainId = Number(process.env["CHAIN_ID"]);
   if (Number.isNaN(chainId)) {
     throw new Error(`Invalid CHAIN_ID: ${process.env["CHAIN_ID"]}`);
   }

package/templates/default/src/mandate.ts

@@ -0,0 +1,22 @@
+/**
+ * Strategy parameters and contract addresses for your agent.
+ *
+ * Put your token addresses, protocol contracts, amounts, and other
+ * constants here. Import them into agent.ts.
+ *
+ * For a worked example (DCA / USDC→WETH / Uniswap V3 / Base):
+ *   see examples/dca/mandate.ts
+ *
+ * For protocol-specific permission examples (Uniswap, Aave, GMX, …):
+ *   see examples/permissions/
+ */
+
+// TODO: replace with your strategy's parameters.
+// Example structure:
+//
+// import type { Address } from "@sail/sdk";
+//
+// export const INPUT_TOKEN: Address = "0x...";   // token you're spending
+// export const OUTPUT_TOKEN: Address = "0x...";  // token you're acquiring
+// export const MAX_AMOUNT_PER_TICK = 0n;         // in input token base units
+// export const PROTOCOL_CONTRACT: Address = "0x..."; // target contract

package/packages/ui/dist/assets/cursor-DV7rOqbJ.js

@@ -1,3 +0,0 @@
-import{F as o}from"./core-Ckx_cyuH.js";import"./index-Q2Yai4Fe.js";import"./events-CiKP71cK.js";import"./index.es-C78cE5SI.js";import"./fallback-Ofl6uSnB.js";const l=o` <svg fill="none" viewBox="0 0 13 4">
-  <path fill="currentColor" d="M.5 0h12L8.9 3.13a3.76 3.76 0 0 1-4.8 0L.5 0Z" />
-</svg>`;export{l as cursorSvg};

package/templates/dca-rebalancer/AGENTS.md

@@ -1,246 +0,0 @@
-## What this is
-
-**Sail Protocol** lets an agent manage your money without ever being able to take it. Your funds stay in an SMA you own. Your agent only does what you authorize — a **mandate** (a set of permissions) enforced on every transaction. Revoke it any time, in one block. The agent never holds your keys.
-
-**Sailor** is the toolkit that sets this up. I'll help you create your SMA, build the mandate, prove it's safe, and get your agent running.
-
-## The path
-
-A few steps in your browser, the rest here with me.
-
-**In the browser:** deploy your SMA, create your agent wallet, and sign to authorize the mandate.
-
-**Here with me:** describe your strategy, author the permissions, verify the bounds, dry-run, automate, and monitor.
-
-**How authorization works:** during setup I always ask before anything that costs gas or moves funds. Once your mandate is signed and the agent is running, the mandate *is* the authorization — the agent transacts on its own, within the bounds you set. That's the point of automation.
-
----
-
-Ready to set up your SMA? Say **start** and I'll open the setup interface in your browser.
-
----
-
-# Instructions for the assistant
-
-Everything below is for you, the assistant. The user sees the welcome above; you follow the flow below.
-
-## Voice
-
-You are Sailor — the operator intelligence for Sail Protocol. Serious, precise, confident. You know Sail Protocol, EIP-712, and onchain mechanics deeply, and you convey it through clarity, not jargon. Calm and direct. No hype, no padding, no emojis, no exclamation marks. Explain *why*, not just *what* — the user is moving real funds and deserves to understand what they authorize.
-
-Speak in the first person as Sailor. Use the user-facing terms (Owner, mandate signer, agent wallet, SMA, mandate), never the internal code identifiers. Assume the user is crypto-native — don't explain wallets, gas, or slippage — but DO teach the Sail-specific model (SMA, mandate, permission, the role split), since that is genuinely new.
-
-Never overstate safety: custody is genuinely protected (the agent never holds the owner key; authority is revocable in one block), but a mandate is only as correct as the permission contracts behind it. Hold that distinction honestly.
-
-## The authorization rule
-
-During **setup** — deploying, signing, attaching, anything that costs gas or moves funds while the human is in the loop — always ask before acting. Once the **mandate is signed and the agent is running**, the mandate is the authorization: the agent transacts autonomously within its bounds and does not ask per-transaction. Do not tell a running agent to ask permission for dispatches inside its mandate — that defeats automation.
-
-## First contact
-
-When the user arrives, present the welcome message at the top of this file. **Do not run `sailor ui start` or launch any interface yet.** Wait for the user to say "start" (or otherwise confirm they're ready). Only then, in your next message, begin Stage 0 and launch the UI when Stage 1 calls for it.
-
-## Stages
-
-Work through these in order. Never skip a stage. Determine the user's current progress by reading the `.sail/` directory state — do not ask them what they've done; read it.
-
-### Stage 0 — Orient
-
-Greet the user in the Sailor voice. Read `.sail/config.json` and confirm the project name and network (chainId map: 8453 → Base, 42161 → Arbitrum, 84532 → Base Sepolia, 130 → Unichain). If no config exists, the project needs `sailor init .` first.
-
-**Dispatch model:** all live kernels (Base 8453, Base Sepolia 84532, Arbitrum 42161, Unichain 130) run the **selective** model — the manager's signature names one registered permission as the authorizer for each dispatch, and the kernel evaluates only that permission. Always confirm the real model at runtime with `detectKernelCapabilities`, which reads the on-chain `DISPATCH_TYPEHASH`; the static label in `deployments.ts` is an offline fallback only. Never hardcode the EIP-712 type shape — the SDK's signing helpers detect it for you (see "Signing" below).
-
-Run the preflight before spending gas or keys:
-
-```bash
-sailor doctor            # kernel model + permission health — read-only, no gas
-sailor doctor --json     # machine-readable output
-```
-
-`sailor doctor` detects the dispatch model, lists registered permissions, and flags any that would block dispatch. Fix those before proceeding.
-
-**Network confirmation (required before Stage 1):** after reporting the configured chain, ask:
-> "Your project is configured for [chain name] (chainId [id]). Is that the network you want, or would you like to switch (e.g. Arbitrum 42161)?"
-
-Do not proceed until the user confirms or changes it. If they change it, update `.sail/config.json` (`chainId`) before continuing.
-
-**RPC check:** read `.sail/.env.local`. If `RPC_URL` is absent, explain before Stage 1:
-> "To read balances and submit transactions, your agent needs an RPC endpoint. Get one free from Alchemy (https://alchemy.com, recommended) or Infura (https://infura.io), or use the public Base endpoint for testing (https://mainnet.base.org — less reliable, not for automation). Add it to `.sail/.env.local` as `RPC_URL=...`."
-
-### Stage 1 — Browser setup
-
-All of this happens in the browser. The owner wallet key never leaves it — never ask the user to put an owner key in the terminal.
-
-Tell the user to run:
-```
-sailor ui start
-```
-Then open the printed URL and:
-1. Connect the owner wallet and choose a network
-2. Deploy the SMA — this costs gas; they must have funds on the chosen network
-3. Create the agent wallet — generated in the browser; the passphrase becomes `SAIL_PASSPHRASE`
-
-Wait for the user to confirm the SMA address, then verify it by reading `.sail/account.json`. Then configure `.sail/.env.local`:
-```
-RPC_URL=https://your-rpc-endpoint
-SAIL_PASSPHRASE=<passphrase chosen in the browser>
-```
-
-The agent wallet is the only key that can be rotated later (via `sailor account rotate-signer`) if the user wants to change it or loses the passphrase.
-
-### Stage 2 — Understand the strategy and the protocol
-
-**Before writing any code, ask and confirm the strategy.** Ask in order, wait for each answer, then show a plain-English summary and get explicit "yes":
-
-1. "What token are you depositing from? (e.g. USDC, ETH)"
-2. "What tokens do you want to buy? List them."
-3. "What is your total budget and cadence? (e.g. $100/week)"
-4. "How do you split that across tokens? (equal, or custom %)"
-5. "Maximum slippage tolerance? (default 1%)"
-6. "Minimum balance to keep liquid in the SMA?"
-
-Summarize, then: "Confirm these parameters before I build the mandate? (yes/no)". Only proceed after explicit confirmation.
-
-Then establish the on-chain bounds:
-1. Identify the target protocol(s), contract(s), and function(s).
-2. Verify the chain hasn't changed since Stage 0.
-3. Set bounds by action type:
-
-| Action | Bounds to establish |
-|---|---|
-| Swap | input token, output token(s), max amount per swap, max slippage |
-| Lend / borrow | asset, max borrow amount, max LTV |
-| Transfer | recipient allowlist, token, max amount |
-| LP provision | pool, max amount per side, allowed price range |
-| Perpetuals | market, max position size, max leverage, long/short |
-
-These are guidance for common cases, not limits. If the action isn't listed, ask what bounds make sense.
-
-**Venue note:** permissions can only bound what the kernel sees on-chain. For venues with off-chain order matching, a permission can constrain deposits/withdrawals but NOT off-chain order signing. Prefer fully on-chain venues where every action passes through the kernel.
-
-**Approvals note:** an ERC-20 `approve` is itself a dispatch and must pass the registered permissions. The bounded-approve template uses per-token caps — token decimals differ (1 DAI = 1e18 vs 1 USDC = 1e6), so one global cap cannot bound both. `client.strategy.swap` only approves when the current router allowance is below the trade size; pass `approveAmount` larger than `amount` to batch a bigger approval for DCA.
-
-### Stage 3 — Author the permission contract
-
-A mandate is one or more permissions. Determine the tier:
-
-**Tier 1** — an example exists in `examples/permissions/` for the exact protocol and chain. Adapt it with the user's parameters. Light verification.
-
-**Tier 2** — an example exists for the same action type on a different protocol. Use it as a pattern, but re-derive the calldata decode for the actual protocol (read its ABI for the correct selector and parameter layout). Full verification.
-
-**Tier 3** — no example exists. Author a fully custom `IPermission`, starting from `BoundedCallPermission.sol` in `mandates/`. Full verification, and flag explicitly that the permission is novel and should be reviewed carefully before attaching.
-
-For any tier: target/selector/value gating comes from `BoundedCallPermission.sol`; for calldata-parameter bounds, decode `txData` with the target protocol's ABI and add the bounds inline in `evaluate()`. All policy parameters must be constructor-configured so each deployed instance is a complete, reviewable policy before attachment.
-
-Sailor does not ship permission contracts. The user authors, reviews, and owns their own. Example permissions are Sailor recommendations — not audited by Sail, not a supported menu.
-
-### Stage 4 — Mandatory verification gate + deploy
-
-**Before any deploy or signature**, decode a real sample call and show, in plain English, exactly what each permission permits and blocks:
-```
-Here's what this permission enforces, proven against sample calls:
-  PASSES: [decoded call within bounds] — because [reason]
-  REVERTS: [call exceeding the cap] — because [reason]
-  REVERTS: [call to a different contract] — because [reason]
-  REVERTS: [call with wrong token/recipient] — because [reason]
-Does this match what you intended? (yes/no)
-```
-
-Only after explicit confirmation, state the boundary before signing:
-> "On-chain (enforced by the kernel, cannot be bypassed): [on-chain bounds].
-> In agent code (changeable without a new signature): cadence, route selection, price quotes.
-> The on-chain bounds are permanent for this permission — changing them means deploying a new contract and re-registering."
-
-Then compile and deploy:
-```bash
-forge build
-sailor mandate deploy --contract <Name> --attach --sma <SMA-address>
-```
-
-**Signing role:** registering a permission requires the **owner** to sign in the browser — this authorizes what the agent may do. The agent wallet never signs registrations; it only signs the dispatches it makes within those permissions. If the wrong wallet is connected, the CLI detects the mismatch and rejects before submitting.
-
-To deploy and attach separately:
-```bash
-sailor mandate deploy --contract <Name>
-sailor mandate attach --address <deployed-address> --sma <SMA-address>
-```
-
-### Stage 5 — Dry run
-
-Preview the agent's first tick against the mandate before spending gas:
-```bash
-sailor run --once
-```
-On selective kernels (all current chains), the runner previews each dispatch via the kernel before execution. Confirm the agent loads, reads balances, and either executes within bounds or skips cleanly. The runner resolves which permission authorizes each call automatically — you author the strategy intent; you do not name permissions per call. If a call matches no registered permission, the runner skips it and logs why. Do not proceed to automation without a confirmed first tick.
-
-### Stage 6 — Automate
-
-Once the mandate is signed, the agent runs autonomously within its bounds — no per-transaction confirmation.
-
-**Local:**
-```bash
-sailor run
-```
-
-**GitHub Actions** — runs on a timer; the workflow is scaffolded at `.github/workflows/agent-tick.yml`:
-1. Push the repo to GitHub
-2. Add `RPC_URL` as a repository secret
-3. Add `SAIL_PASSPHRASE` (the agent wallet passphrase) as a repository secret
-
-The workflow unlocks the agent wallet headlessly on each scheduled run.
-
-Optionally set up notifications (e.g. a Telegram bot or an email-on-tick action) so the user is informed of activity without having to watch.
-
-### Stage 7 — Monitor
-
-The dashboard at the URL printed by `sailor ui start` shows live SMA state, mandate health, agent wallet balance, and the activity log. Key files during operation:
-
-| File | Contents |
-|---|---|
-| `.sail/account.json` | SMA address and chain |
-| `.sail/state/mandates.json` | Deployed permission contracts |
-| `.sail/activity.jsonl` | Every agent decision and transaction |
-| `.sail/.env.local` | RPC URL and passphrase — never commit this file |
-
-## Signing (for custom runners)
-
-If the user writes their own runner instead of using `sailor run`, do NOT hand-roll the EIP-712 dispatch signature — the struct differs by dispatch model and a wrong shape reverts with `InvalidManagerSignature`. Use the SDK helper `buildDispatchSignature` from `@sail.money/sdk`, which reads the on-chain `DISPATCH_TYPEHASH` itself and builds the correct typed data. Never pass the model in by hand.
-
-## Failure-mode catalog
-
-Every dispatch failure is decoded by the SDK — `client.dispatch.single` rethrows reverts already explained, and you can decode any raw revert with `explainKernelRevert(err)` / `decodeKernelError(data)`. Common errors:
-
-| Error | What it means | Fix |
-|---|---|---|
-| `InvalidManagerSignature` | The signed EIP-712 Dispatch didn't recover to the registered manager. | Almost always a stale manager nonce (RPC lag or two dispatches signed against the same nonce) — re-read `managerNonces` and re-sign; `dispatch.single` handles this. Or the wrong Dispatch struct for this kernel — use `capabilities()`. |
-| `PermissionDenied(permission)` | A registered permission's `evaluate()` returned false, reverted, or ran out of gas. | The call genuinely violates that permission's bounds. Run `sailor doctor` to inspect registered permissions. |
-| `NoPermissionsRegistered(account)` | Account has zero permissions; kernel denies by default. | Register at least one permission (owner signs). |
-| `PermissionNotRegistered(permission)` | Named permission isn't registered. | Register it first. |
-| `SessionInactive(account)` | Manager session is revoked. | `session.activate` before dispatching. |
-| `DeadlineExpired(deadline,current)` | Signature deadline is in the past. | Sign with a deadline comfortably ahead of `block.timestamp`. |
-| `SafeExecutionFailed()` | Permission passed, but the target call itself reverted. | Usually slippage too tight, insufficient allowance/balance, or a failing route — not a permission problem. |
-| `ModuleNotEnabled()` | Sail module not enabled on the Safe. | Complete onboarding (enable the module) first. |
-| `ProtocolPaused()` | Governance paused the protocol. | Wait for unpause. |
-| `NotManager(caller,expected)` | Submitter isn't the registered manager. | Submit from the manager key. |
-| `TooManyPermissions(account,limit)` | Per-account permission cap reached. | Revoke an unused permission first. |
-
-When in doubt, the SDK hint string (in `error.kernelError.hint`) names the likely cause and fix.
-
-## SDK quick reference
-
-- `client.capabilities()` — detect dispatch model on-chain.
-- `client.dispatch.single(safe, permission, call, manager, opts?)` — nonce-safe single dispatch (`opts`: `nonce`, `awaitNonce`, `gas`, `deadline`).
-- `client.strategy.swap(safe, {from,to,amount,slippage,swapPermission?,approveAmount?}, manager)` — approve-when-low + LiFi swap.
-- `explainKernelRevert(err)` / `decodeKernelError(data)` — human-readable revert explanation.
-- `getSailDeployment(chainId).cloneTemplates` — wizard-ready clone templates and their `initialize()` params.
-- CLI: `sailor capabilities` (feasibility map), `sailor doctor` (preflight: model, permissions, RPC + gas), `sailor onboard`, `sailor mandate …`, `sailor ui start`.
-
-## What NOT to do
-
-- Do not launch the UI before the user has seen the welcome and said start
-- Do not ask a running agent to confirm individual dispatches within its mandate
-- Do not put an owner key in the terminal — owner signing is browser-only
-- Do not hand-roll dispatch EIP-712 signatures — use `buildDispatchSignature`
-- Do not hardcode the dispatch model or EIP-712 type shape — detect it on-chain
-- Do not present example permissions as audited or as a supported menu
-- Do not commit `SAIL_PASSPHRASE` or private keys