@dev.sail.money/sailor 0.0.2-23 → 0.0.2-27

package/AGENTS.md

@@ -8,9 +8,8 @@ tooling to create SMAs, register permission contracts, and run strategy agents.
 
 | Package / path | Name | Role |
 |---|---|---|
-| `packages/sdk` | `@sail/sdk` | SailorClient, LocalKeyring, kernel ABIs, EIP-712 builders, deployment registry |
+| `packages/sdk` | `@sail/sdk` | SailorClient, LocalKeyring, kernel ABIs, EIP-712 builders, deployment registry, per-chain address registry |
 | `packages/cli` | `sailor` | CLI: init, keys, account, mandate, onboard, station, ui, run, session, scan, status, owner, doctor, capabilities |
-| `packages/chains` | `@sail/chains` | Per-chain address registry (kernel, mandateFactory, governance) |
 | `packages/ui` | `sailor-ui` | Local dashboard + browser-driven onboarding wizard at localhost:3333 |
 | `templates/default` | — | Default agent starter: neutral blank scaffold + Foundry workspace + onboarding guide (AGENTS.md) |
 | `templates/custom-mandate` | — | Solidity reference: IPermission scaffold (not a project template) |

package/README.md

@@ -10,8 +10,8 @@ Sailor is the operator layer for [Sail Protocol](../SailProtocol): the tooling a
 
 | Package | Name | Role |
 |---|---|---|
-| `packages/sdk` | `@sail/sdk` | TypeScript library wrapping SailKernel and MandateFactory |
-| `packages/cli` | `sailor` | CLI for account setup, mandate signing, and agent execution |
+| `packages/sdk` | `@sail/sdk` (internal) | TypeScript library: SailorClient, EIP-712 helpers, ABIs, chain registry |
+| `packages/cli` | `@sail.money/sailor` | CLI for account setup, mandate signing, and agent execution |
 | `packages/chains` | `@sail/chains` | Per-chain address registry (EVM-compatible) |
 | `packages/ui` | `sailor-ui` | Local dashboard running on localhost:3333 |
 | `templates/default` | — | Default agent starter (neutral; what `sailor init` scaffolds) |
@@ -74,7 +74,7 @@ Prerequisites:
 - Node.js 18+
 - A wallet (MetaMask or Rabby)
 - An RPC URL (e.g. Alchemy free tier)
-- A supported chain: **Base, Base Sepolia, Arbitrum, or Unichain** — verified deployments are bundled in `@sail/sdk`, no `@sail/chains` entry needed. Other chains require addresses in `@sail/chains`.
+- A supported chain: **Base, Base Sepolia, Arbitrum, or Unichain** — verified deployments are bundled in `@sail.money/sailor`.
 
 ### Recommended — assistant-driven
 
@@ -187,8 +187,7 @@ sailor ui stop
 
 ## Agent-driven onboarding & custom mandates
 
-For chains with a bundled Sail deployment (Base, Base Sepolia, Arbitrum, Unichain — shipped
-in `@sail/sdk`, no `@sail/chains` entry required), an agent can drive the whole
+For chains with a bundled Sail deployment (Base, Base Sepolia, Arbitrum, Unichain), an agent can drive the whole
 setup through a browser **signing station**. The station is a local HTTP +
 WebSocket daemon that bridges the CLI and the owner's wallet: the agent never
 holds the owner key — it pushes signing requests, the owner approves them in the
@@ -246,6 +245,60 @@ non-interactively. No private key ever appears in the workflow file or in secret
 
 ---
 
+## Packages
+
+Sailor ships as a **single npm package** — the SDK is bundled inside it and exposed via a subpath export:
+
+| Package | Contents |
+|---|---|
+| `@sail.money/sailor` | CLI binary, UI server, templates, examples, and SDK |
+
+```bash
+npm install @sail.money/sailor        # latest stable
+npm install @sail.money/sailor@dev    # latest dev build
+```
+
+The SDK is available as a subpath export for use in agent code:
+
+```ts
+import type { Agent, AgentContext, Dispatch } from '@sail.money/sailor/sdk'
+```
+
+Dev builds carry a prerelease version suffix and are published under the `dev` dist-tag; production releases use `latest`:
+
+| Trigger | Version | dist-tag |
+|---|---|---|
+| Tag push (`v*`) | `1.0.0` | `latest` |
+| Manual dispatch | `1.0.0-42` | `dev` |
+
+### Publishing flow
+
+A single CI job builds sailor and publishes it to npm. No separate SDK publish step — the SDK dist lives inside the sailor package and is accessed via the `./sdk` subpath export.
+
+The workflow (`publish-npm.yml`) calls the reusable `publish-npm-public-pkg.yaml`:
+- Tag push → version unchanged, dist-tag `latest`
+- Manual dispatch → version stamped with run number (e.g. `1.0.0-42`), dist-tag `dev`
+
+### GitHub Packages
+
+`@sailagent/sailor` is also published to GitHub Packages for internal testing — no public npm registry required. GitHub Packages requires the `@sailagent` scope; install it with:
+
+```bash
+npm install @sailagent/sailor --registry https://npm.pkg.github.com
+```
+
+To keep `@sail.money/sailor/sdk` imports working in agent code when installing from GitHub Packages, add a package alias to your project's `package.json`:
+
+```json
+"dependencies": {
+  "@sail.money/sailor": "npm:@sailagent/sailor"
+}
+```
+
+This resolves `@sail.money/sailor` (and its `./sdk` subpath) to the `@sailagent/sailor` package transparently.
+
+---
+
 ## Architecture
 
 ```
@@ -268,7 +321,7 @@ non-interactively. No private key ever appears in the workflow file or in secret
    │  (register perms)  │  │      (custody)     │  │  (named, per-call) │
    └────────────────────┘  └────────────────────┘  └────────────────────┘
 
-          sailor CLI / @sail/sdk drive both signing paths above.
+          sailor CLI / @sail.money/sailor/sdk drive both signing paths above.
           .sail/ (account · mandate · activity) ──→ sailor-ui (localhost:3333)
 ```
 
@@ -290,13 +343,13 @@ The CLI and SDK sit between the operator and SailKernel: they build the EIP-712
 
 Sailor is functional and published as [`@sail.money/sailor`](https://www.npmjs.com/package/@sail.money/sailor) on npm (v0.0.1). The SDK, CLI, keystore, mandate flows, agent runner, and dashboard are implemented and have been exercised end to end against Base Sepolia.
 
-The Sail Protocol trusted core is deployed on Base, Base Sepolia, Arbitrum, and Unichain as staging deployments for testing ahead of a formal launch. All four run the selective dispatch model, with verified deployments bundled in `@sail/sdk`. These deployments are under an ongoing external audit by [Octane Security](https://octane.security) and are not final — do not use them with funds you are not prepared to lose. Permission templates are not yet deployed against the Base, Arbitrum, and Base Sepolia kernels; **Unichain** ships the full template suite (7 shared + 12 standalone, source-verified) and its template registries in `@sail/sdk` are populated. `@sail/chains` and the remaining template registries will be filled in as templates are deployed on the other chains and at mainnet launch.
+The Sail Protocol trusted core is deployed on Base, Base Sepolia, Arbitrum, and Unichain as staging deployments for testing ahead of a formal launch. All four run the selective dispatch model, with verified deployments bundled in `@sail.money/sailor`. These deployments are under an ongoing external audit by [Octane Security](https://octane.security) and are not final — do not use them with funds you are not prepared to lose. Permission templates are not yet deployed against the Base, Arbitrum, and Base Sepolia kernels; **Unichain** ships the full template suite (7 shared + 12 standalone, source-verified) and its template registries are populated. The remaining template registries will be filled in as templates are deployed on the other chains and at mainnet launch.
 
 ---
 
 ## Deployments
 
-The Sail Protocol trusted core is live on the following chains as **staging deployments** ahead of a formal launch, bundled in `@sail/sdk`. All run the selective dispatch model with zero fees. Permission templates are not yet deployed against the Base, Arbitrum, and Base Sepolia kernels; **Unichain** ships the full template suite (7 shared + 12 standalone, source-verified on uniscan.xyz) and has its onboarding allowlists seeded at genesis.
+The Sail Protocol trusted core is live on the following chains as **staging deployments** ahead of a formal launch. All addresses are bundled in `@sail.money/sailor` and run the selective dispatch model with zero fees. Permission templates are not yet deployed against the Base, Arbitrum, and Base Sepolia kernels; **Unichain** ships the full template suite (7 shared + 12 standalone, source-verified on uniscan.xyz) and has its onboarding allowlists seeded at genesis.
 
 ### Base (8453)
 
@@ -348,9 +401,7 @@ First chain to ship the full permission-template suite (7 shared + 12 standalone
 | SafeModuleEnabler | `0xFE9227A9F2baf704060c604466df354a5A137b9B` |
 | Treasury | `0xB01dCE443d052e44b7D13726c0EC9fFB7f5815B6` |
 
-The 19 template addresses are in `@sail/sdk` (`knownTemplates` + `standaloneTemplates` for chain 130).
-
-Addresses are sourced from `@sail/sdk` (`packages/sdk/src/deployments.ts`), the canonical registry.
+The 19 template addresses are in `packages/sdk/src/deployments.ts` (`knownTemplates` + `standaloneTemplates` for chain 130).
 
 ---
 

package/examples/permissions/BoundedSupply_AaveV3_Arbitrum.sol

@@ -33,6 +33,7 @@ pragma solidity 0.8.26;
 // ─────────────────────────────────────────────────────────────────────────────
 
 import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
+import {SailCalldata} from "./SailCalldata.sol";
 
 contract BoundedSupply_AaveV3_Arbitrum is IPermission {
     bytes32 private constant DISCRIMINATOR = keccak256("BoundedSupply_AaveV3_Arbitrum");
@@ -63,15 +64,12 @@ contract BoundedSupply_AaveV3_Arbitrum is IPermission {
         if (ctx.target != AAVE_POOL)    return false;
         if (ctx.selector != SEL_SUPPLY) return false;
         // supply(address asset, uint256 amount, address onBehalfOf, uint16 referralCode)
-        // = 4 ABI-encoded 32-byte slots after the 4-byte selector
-        if (txData.length < 4 + 4 * 32) return false;
+        if (!SailCalldata.hasParams(txData, 4)) return false;
 
-        (
-            address asset,
-            uint256 amount,
-            address onBehalfOf,
-            /* uint16 referralCode — not bounded */
-        ) = abi.decode(txData[4:], (address, uint256, address, uint16));
+        address asset      = SailCalldata.asAddress(txData, 0);
+        uint256 amount     = SailCalldata.asUint256(txData, 1);
+        address onBehalfOf = SailCalldata.asAddress(txData, 2);
+        // slot 3 = referralCode (uint16) — informational, not bounded
 
         if (!isAllowedAsset[asset])       return false;
         if (amount > MAX_SUPPLY_AMOUNT)   return false;

package/examples/permissions/SailCalldata.sol

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SailCalldata — safe static-parameter extraction for IPermission.evaluate()
+//
+// PROBLEM
+//   evaluate(bytes calldata txData, Context calldata ctx) receives raw ABI-
+//   encoded calldata. Extracting parameters by hand is the most dangerous part
+//   of permission writing:
+//     • Forgetting the length check before decoding → silent wrong value or
+//       revert instead of clean `return false`.
+//     • Wrong slot index → decoding the wrong parameter (type-checks, still wrong).
+//     • Truncation bugs when casting uint256 slots to address (padding bits).
+//
+// SOLUTION
+//   This library centralises the three operations into named helpers:
+//     1. hasParams()  — explicit length guard (call once, at the top of evaluate)
+//     2. asAddress()  — extract + mask to 20 bytes
+//     3. asUint256(), asInt256(), asBytes32(), asBool(), asUint128() — typed slots
+//
+//   All helpers are view/pure and add zero gas overhead beyond the slice itself.
+//
+// USAGE (replace abi.decode pattern)
+//
+//   // Before:
+//   if (txData.length < 4 + 3 * 32) return false;
+//   (address asset, uint256 amount, address onBehalfOf) =
+//       abi.decode(txData[4:], (address, uint256, address));
+//
+//   // After:
+//   if (!SailCalldata.hasParams(txData, 3)) return false;
+//   address  asset      = SailCalldata.asAddress(txData, 0);
+//   uint256  amount     = SailCalldata.asUint256(txData, 1);
+//   address  onBehalfOf = SailCalldata.asAddress(txData, 2);
+//
+// LIMITATIONS
+//   Only covers static (fixed-size) ABI types. Dynamic types (bytes, string,
+//   arrays) use pointer indirection — decode them with abi.decode(txData[4:], ...)
+//   after the hasParams() guard, or write a dedicated extractor.
+//
+// SLOT INDEXING
+//   Slots are 0-indexed from the first constructor parameter (after the 4-byte
+//   selector). Slot 0 = bytes [4..35], slot 1 = bytes [36..67], etc.
+// ─────────────────────────────────────────────────────────────────────────────
+
+library SailCalldata {
+    // ── Guards ────────────────────────────────────────────────────────────────
+
+    /// @notice Returns true when txData is long enough to hold `params` static
+    ///         32-byte ABI slots after the 4-byte selector.
+    /// @dev    Call this once at the top of evaluate() before any slot access.
+    ///         Returns false (not revert) so evaluate() can return false cleanly.
+    function hasParams(bytes calldata txData, uint256 params) internal pure returns (bool) {
+        return txData.length >= 4 + params * 32;
+    }
+
+    // ── Static-type extractors ────────────────────────────────────────────────
+    // All assume hasParams() has already been checked for the relevant slot.
+    // Accessing an out-of-bounds slot will cause the calldata slice to revert —
+    // always guard with hasParams() first.
+
+    /// @notice Extract an address from ABI slot `i` (0-indexed after selector).
+    ///         Masks to 20 bytes, discarding the ABI zero-padding in the upper 12.
+    function asAddress(bytes calldata txData, uint256 i) internal pure returns (address) {
+        return address(uint160(uint256(bytes32(txData[4 + i * 32 : 4 + (i + 1) * 32]))));
+    }
+
+    /// @notice Extract a uint256 from ABI slot `i`.
+    function asUint256(bytes calldata txData, uint256 i) internal pure returns (uint256) {
+        return uint256(bytes32(txData[4 + i * 32 : 4 + (i + 1) * 32]));
+    }
+
+    /// @notice Extract an int256 from ABI slot `i`.
+    function asInt256(bytes calldata txData, uint256 i) internal pure returns (int256) {
+        return int256(uint256(bytes32(txData[4 + i * 32 : 4 + (i + 1) * 32])));
+    }
+
+    /// @notice Extract a bytes32 from ABI slot `i`.
+    function asBytes32(bytes calldata txData, uint256 i) internal pure returns (bytes32) {
+        return bytes32(txData[4 + i * 32 : 4 + (i + 1) * 32]);
+    }
+
+    /// @notice Extract a bool from ABI slot `i` (true when slot value is non-zero).
+    function asBool(bytes calldata txData, uint256 i) internal pure returns (bool) {
+        return asUint256(txData, i) != 0;
+    }
+
+    /// @notice Extract a uint128 from ABI slot `i` (lower 128 bits of the slot).
+    function asUint128(bytes calldata txData, uint256 i) internal pure returns (uint128) {
+        return uint128(asUint256(txData, i));
+    }
+
+    /// @notice Extract a uint64 from ABI slot `i`.
+    function asUint64(bytes calldata txData, uint256 i) internal pure returns (uint64) {
+        return uint64(asUint256(txData, i));
+    }
+
+    /// @notice Extract a uint32 from ABI slot `i`.
+    function asUint32(bytes calldata txData, uint256 i) internal pure returns (uint32) {
+        return uint32(asUint256(txData, i));
+    }
+
+    /// @notice Extract a uint24 from ABI slot `i` (e.g. Uniswap fee tier).
+    function asUint24(bytes calldata txData, uint256 i) internal pure returns (uint24) {
+        return uint24(asUint256(txData, i));
+    }
+
+    /// @notice Extract a uint16 from ABI slot `i` (e.g. Aave referral code).
+    function asUint16(bytes calldata txData, uint256 i) internal pure returns (uint16) {
+        return uint16(asUint256(txData, i));
+    }
+
+    /// @notice Extract bytes4 (a function selector) from ABI slot `i`.
+    function asBytes4(bytes calldata txData, uint256 i) internal pure returns (bytes4) {
+        return bytes4(asBytes32(txData, i));
+    }
+}

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "@dev.sail.money/sailor",
-  "version": "0.0.2-23",
+  "version": "0.0.2-27",
   "description": "Operator toolkit for Sail Protocol",
   "bin": {
     "sailor": "packages/cli/dist/index.cjs"
   },
+  "exports": {
+    "./sdk": {
+      "import": "./packages/sdk/dist/index.js",
+      "types": "./packages/sdk/dist/index.d.ts"
+    }
+  },
   "files": [
     "packages/cli/dist",
     "packages/sdk/dist",
@@ -18,12 +24,12 @@
     "AGENTS.md"
   ],
   "scripts": {
-    "build": "pnpm --filter @sail/sdk build && pnpm --filter @sail/chains build && pnpm --filter sailor build && pnpm --filter sailor-ui build",
+    "build": "pnpm --filter @sail/sdk build && pnpm --filter sailor build && pnpm --filter sailor-ui build",
     "test": "pnpm --filter sailor-ui test",
     "test:ui": "pnpm --filter sailor-ui test:ui",
     "link:cli": "pnpm link --global",
     "postinstall": "node scripts/postinstall.js",
-    "typecheck": "pnpm --filter @sail/sdk build && pnpm --filter @sail/chains build && pnpm -r typecheck",
+    "typecheck": "pnpm --filter @sail/sdk build && pnpm -r typecheck",
     "docs:check": "node scripts/check-docs.mjs",
     "init:check": "node scripts/check-init.mjs",
     "eval": "node evals/run.mjs",