@mysten-incubation/sui-agent-pass 0.1.4 → 0.1.6

package/README.md

@@ -61,7 +61,11 @@ npm install -g @mysten-incubation/sui-agent-pass
 agent-pass connect   # pick the agents on this machine; nothing stays running
 ```
 
-That is the only command. Then open the agent and tell it what to do with your money. It
+That is the only command. For each agent you pick it registers the MCP server and links the
+`agent-pass` skill, the playbook built into the package, into the agent's skills folder (Claude
+Code, Codex, Cursor and Hermes), so the agent has the tools and the guidance for them. A link
+follows upgrades; rerun `connect` if you installed through `npx`. Then open the agent and tell
+it what to do with your money. It
 proposes a pass (`propose_authorization`) and opens the review page with the proposal in its URL.
 Connect a wallet, check the rules the agent quoted to you, and sign once; the session key stays
 local, and the agent sees your signature land on chain and acts within the rules. Claude Code
@@ -334,11 +338,8 @@ brand` and `npx playwright install chromium`.
 - [Agent transaction guide](docs/AGENT.md): complete interface and agent-side examples.
 - [Architecture and boundaries](docs/ARCHITECTURE.md).
 - [Status: implemented and todo](docs/STATUS.md).
-- [Verification record](docs/VERIFICATION.md) and [generated chain evidence](docs/evidence/localnet.json),
-  including the explorer's [pass page](docs/evidence/explorer-pass.png) and
-  [booth view](docs/evidence/explorer-booth.png).
-- [Real Claude execution evidence](docs/evidence/claude.json): Claude Code with the plugin,
-  from prompt to signed pass to on-chain actions on a localnet.
+- [Verification record](docs/VERIFICATION.md): dated runs with their digests. The test scripts
+  write their reports and screenshots to `.local/evidence/`, which stays out of git.
 
 ## Checks
 

package/dist/cli.js

@@ -3,9 +3,9 @@
 // SPDX-License-Identifier: Apache-2.0
 import { spawn } from 'node:child_process';
 import { realpathSync } from 'node:fs';
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { access, cp, lstat, mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { select } from '@inquirer/prompts';
 import { Command } from 'commander';
@@ -174,6 +174,45 @@ async function registerClient(client, http) {
             console.log(JSON.stringify({ mcpServers: { 'agent-pass': http ?? stdio } }, null, 2));
     }
 }
+/** Where each agent loads personal skills from, under the home directory. */
+const SKILL_DIRS = {
+    'claude-code': '.claude/skills',
+    codex: '.codex/skills',
+    cursor: '.cursor/skills',
+    hermes: '.hermes/skills',
+};
+/**
+ * Puts the agent-pass skill, the playbook built into this package, where the client loads
+ * skills. A link follows upgrades of the package; an npx cache is temporary, so it gets a copy.
+ */
+async function installSkill(client) {
+    const source = fileURLToPath(new URL('../skills/agent-pass', import.meta.url));
+    if (!(await access(join(source, 'SKILL.md')).then(() => true, () => false)))
+        throw new Error(`The skill is missing from ${source}; run npm run build`);
+    const dir = SKILL_DIRS[client];
+    if (!dir) {
+        console.log(client === 'claude-desktop'
+            ? `Claude Desktop takes skills from its own settings; add ${join(source, 'SKILL.md')} there to give it the playbook.`
+            : `If the agent loads SKILL.md skills, link ${source} into its skills folder to give it the playbook.`);
+        return;
+    }
+    const target = join(homedir(), dir, 'agent-pass');
+    const existing = await lstat(target).catch(() => null);
+    if (existing && !existing.isSymbolicLink()) {
+        const ours = await readFile(join(target, 'SKILL.md'), 'utf8').then((t) => /^name: agent-pass$/m.test(t), () => false);
+        if (!ours)
+            throw new Error(`${target} exists and is not the agent-pass skill; move it away first`);
+    }
+    if (existing)
+        await rm(target, { recursive: true, force: true });
+    await mkdir(dirname(target), { recursive: true });
+    const temporary = source.includes(`${sep}_npx${sep}`);
+    if (temporary)
+        await cp(source, target, { recursive: true });
+    else
+        await symlink(source, target, 'dir');
+    console.log(`${temporary ? 'Copied' : 'Linked'} the agent-pass skill into ${target}.`);
+}
 /** The agents on this machine, as far as their usual files show; nothing is preselected. */
 async function chooseClients() {
     const home = homedir();
@@ -234,10 +273,12 @@ program
         http = { url: mcpUrl, headers: { Authorization: `Bearer ${await store.mcpToken()}` } };
     }
     const clients = o.client ? [o.client] : await chooseClients();
-    for (const client of clients)
+    for (const client of clients) {
         await registerClient(client, http);
+        await installSkill(client);
+    }
     if (!http)
-        console.log('\nDone. Open the agent and tell it what to do with your money; it proposes the pass, you review and sign in your wallet, and it acts within the rules. Restart the agent after upgrading this package so it loads the new server.');
+        console.log('\nDone. Open the agent and tell it what to do with your money; it proposes the pass, you review and sign in your wallet, and it acts within the rules. Restart the agent after upgrading this package so it loads the new server and skill.');
 });
 // Run only when this file is the entry: directly, through tsx in development, or through the
 // package's `agent-pass` bin, which is a symlink to it.

package/dist/plugin.js

@@ -20,7 +20,7 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { Transaction } from '@mysten/sui/transactions';
 import { fromBase64, normalizeSuiAddress } from '@mysten/sui/utils';
 import { z } from 'zod';
-import { clientFor, deepbookSizes, quoteSwap, readStatus, withMarketFacts } from './chain.js';
+import { clientFor, deepbookSizes, quoteSwap, readAllHoldings, readStatus, withMarketFacts, } from './chain.js';
 import { describePolicy, describeSetup, renderRows } from './describe.js';
 import { address, coinBySymbol, coinInfo, DAY_MS, defaultGasDaily, DeploymentSchema, display, isStable, limitUnits, poolsFor, recipientName, sameCoin, SetupSchema, showCoin, units, VenueSchema, } from './domain.js';
 import { passesByAgent } from './explorer.js';
@@ -411,10 +411,14 @@ export function createPluginMcp(registry) {
     });
     registerDocs(server);
     server.registerTool('list_passes', {
-        description: 'List the pass sessions on this machine (id, name, network, whether the owner has authorized it on chain) and the networks a new pass can live on, each with the coins and pools its rules may name.',
-        inputSchema: {},
+        description: 'List the pass sessions on this machine (id, name, network, whether the owner has authorized it on chain) and the networks a new pass can live on, each with its listed coins and pools and how to name others. With owner, also every coin that address holds on each network, so rules can be sized from real balances before any pass exists.',
+        inputSchema: {
+            owner: address
+                .optional()
+                .describe("the owner's address, when they gave it; adds ownerCoins per network"),
+        },
         annotations: { readOnlyHint: true },
-    }, async () => {
+    }, async ({ owner }) => {
         const path = registry.deploymentPath();
         // What the pool pays for ten units of its non-stable coin (coinA when neither or both are
         // stablecoins), quoted like a rule's price; ten clears DeepBook's minimum order.
@@ -438,10 +442,15 @@ export function createPluginMcp(registry) {
             }))),
             lending: Object.keys(d.protocols.navi.reserves).map((c) => coinInfo(d, c).symbol),
             ...(d.pools.length || Object.keys(d.protocols.navi.reserves).length
-                ? {}
+                ? {
+                    otherCoins: 'These are the coins and pools this package lists, not all it can use. Any other coin the owner holds goes in a transfer or swap rule by its full type; a swap of it also needs, in pools, the id of a DeepBook or Cetus pool holding exactly that pair. The server reads the coin and the pool from chain. Lending stays with the listed coins.',
+                }
                 : {
                     note: 'Transfers and staking only: this network lists no pools and no NAVI reserves, so swap and lending rules are refused here.',
                 }),
+            ...(owner
+                ? { ownerCoins: await readAllHoldings(clientFor(d), d, owner).catch(() => null) }
+                : {}),
         });
         const own = (await exists(path)) ? [await markets(await registry.deployment())] : [];
         const bundled = await Promise.all((await registry.bundledNetworks()).map(async (n) => markets(await registry.bundled(n))));

package/docs/PLAYBOOK.md

@@ -53,13 +53,15 @@ it; say so when the owner picks one.
 pool), so list Cetus as well when trades will be small. A network may list no pools or no NAVI
 reserves; `list_passes` says so, and swap or lending rules are refused there.
 
-**Coins and pools.** Name a coin by symbol when `list_passes` lists it for the network. Name any
-other coin the owner holds (`session_info.ownerCoins` for an existing pass, or a `listBalances`
-read of the owner's address) by its full type, and give the id of a
-DeepBook or Cetus pool holding exactly that pair in `pools`. The server and the review page read
-such a coin's symbol and decimals and such a pool's venue from chain, never from you, and the
-page shows an unlisted coin with its type so the owner can tell a look-alike from the real one.
-Lending is limited to the coins the network lists as NAVI reserves.
+**Coins and pools.** The coins and pools `list_passes` shows for a network are the ones this
+package lists, not the only ones it can use. Name a listed coin by symbol. Name any other coin
+the owner holds by its full type, and for a swap give the id of a DeepBook or Cetus pool holding
+exactly that pair in `pools`. To find the type and the balance, ask the owner for their address
+and call `list_passes` with `owner`: it adds every coin that address holds per network. For the
+pool, ask the owner or look the pair up on the venue's own site. The server and the review page
+read such a coin's symbol and decimals and such a pool's venue from chain, never from you, and
+the page shows an unlisted coin with its type so the owner can tell a look-alike from the real
+one. Lending is limited to the coins the network lists as NAVI reserves.
 
 **Lifetime caps.** `caps` gives, per coin, the total the key may ever withdraw, for exactly the
 coins the rules spend (staking spends SUI). A daily limit may not exceed its coin's cap. Size

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mysten-incubation/sui-agent-pass",
-	"version": "0.1.4",
+	"version": "0.1.6",
 	"type": "module",
 	"description": "AI builds transactions. A session signer signs. Your pass enforces the rules.",
 	"repository": {
@@ -26,6 +26,7 @@
 		"deployments",
 		"docs/AGENT.md",
 		"docs/PLAYBOOK.md",
+		"skills",
 		"README.md",
 		"LICENSE"
 	],
@@ -37,7 +38,7 @@
 		"node": ">=22"
 	},
 	"scripts": {
-		"build": "tsc && vite build",
+		"build": "tsc && vite build && node scripts/skill.mjs",
 		"prepublishOnly": "npm run build",
 		"check": "tsc -p tsconfig.tools.json && tsc -p tsconfig.web.json",
 		"test": "node --import tsx --test tests/*.test.ts",

package/skills/agent-pass/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: agent-pass
+description: "Set up and use a Sui Agent Pass: turn a request such as \"sell up to 0.5 SUI a day for USDC at no less than 0.95, for a week\" into on-chain rules the owner signs once in their wallet, then trade, transfer, stake, lend and borrow within them through the agent-pass MCP server. Use for giving an agent money to manage on Sui, any Sui swap, transfer, staking or NAVI lending request, including coins not listed by default, checking or changing a pass, or ending one."
+---
+
+# Agent playbook
+
+How an agent sets up a pass from an owner's request, acts within its rules, reports on it,
+changes it and ends it. Every MCP client gets this text as the `agent-pass://playbook` resource;
+the SDK and the contract interface are in `agent-pass://guide` ([`docs/AGENT.md`](AGENT.md)).
+
+## How a pass works
+
+The owner's coins stay in the owner's address. The owner signs once in their own wallet, and
+that one transaction creates a pass holding the rules, issues allowances over the owner's
+balance that only the pass can spend, and gives the agent key its gas. You act with that agent
+key, which the signer holds and you never see. Each action is a transaction that draws on an
+allowance and that the chain checks against the rules; proceeds go back to the owner's address,
+never to you. A position you open (a NAVI account, a stake) sits in the pass, and only the owner
+can take it out.
+
+A signature from the signer is not permission. Only a successful on-chain execution is.
+
+Respond in English. Amounts are exact decimals in each coin's own units; `list_passes` and
+`session_info` give every coin's decimals. Dates are UTC, and a day is a UTC calendar day. Off
+mainnet the stablecoin is a test token and the markets are stand-ins; transfers and staking are
+real everywhere.
+
+## 1. Turn the request into rules
+
+Map what the owner asks for onto the rule sets below. Anything they did not ask for is not
+allowed: leave it out. One rule per coin, per swap direction and per lending coin; a coin without
+a rule cannot be touched.
+
+Three things only the owner can supply. Ask for them; never fill them in:
+
+- **Recipients.** Every transfer goes to a named address the owner gave you.
+- **Prices.** Every swap rule needs the owner's price limit. When they have not said one, show
+  them the pool's current price from `list_passes` and ask what they accept.
+- **Amounts.** When a limit is missing, ask, or propose a conservative one and say that you did.
+
+Every limit must be above zero; there is no "no limit".
+
+| Rule set    | Fields                                                                                                                                | What the chain enforces                                                                                                                               |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `transfers` | `coin`, named recipients (name and address), per transfer, per day                                                                    | only those recipients ever receive that coin                                                                                                          |
+| `swaps`     | `sell`, `buy`, optional `venues` (`deepbook`, `cetus`; every listed pool for the pair when omitted), per trade, per day, `limitPrice` | only listed pools; limits on the sold coin; every fill at the price limit or better                                                                   |
+| `lending`   | `coin`, `allowBorrow`, per action, per day, `minHealthFactor` (or null)                                                               | NAVI only; supply and withdraw, plus borrow and repay when allowed; a withdraw or borrow that would take the health factor under the floor is refused |
+| `staking`   | validators (empty for any active one), SUI per stake, per day                                                                         | only those validators; at least 1 SUI per stake; the stake stays in the pass                                                                          |
+
+**Prices.** When one coin of a pair is a stablecoin, `limitPrice` is in that stablecoin per one
+of the other coin: the most the agent pays when buying, the least it accepts when selling. For
+other pairs it is the bought coin per one sold coin, the least accepted. The limit is fixed when
+the owner signs, so a limit close to the market refuses every trade once the price moves past
+it; say so when the owner picks one.
+
+**Venues.** DeepBook fills nothing under a pool's minimum order (1 SUI on the mainnet SUI/USDC
+pool), so list Cetus as well when trades will be small. A network may list no pools or no NAVI
+reserves; `list_passes` says so, and swap or lending rules are refused there.
+
+**Coins and pools.** The coins and pools `list_passes` shows for a network are the ones this
+package lists, not the only ones it can use. Name a listed coin by symbol. Name any other coin
+the owner holds by its full type, and for a swap give the id of a DeepBook or Cetus pool holding
+exactly that pair in `pools`. To find the type and the balance, ask the owner for their address
+and call `list_passes` with `owner`: it adds every coin that address holds per network. For the
+pool, ask the owner or look the pair up on the venue's own site. The server and the review page
+read such a coin's symbol and decimals and such a pool's venue from chain, never from you, and
+the page shows an unlisted coin with its type so the owner can tell a look-alike from the real
+one. Lending is limited to the coins the network lists as NAVI reserves.
+
+**Lifetime caps.** `caps` gives, per coin, the total the key may ever withdraw, for exactly the
+coins the rules spend (staking spends SUI). A daily limit may not exceed its coin's cap. Size
+each cap to cover the days of the term, a little above the sum of the daily limits: the chain
+checks the cap before the daily limit, so a cap equal to one day's limit turns a "daily limit"
+refusal into a "lifetime cap" one.
+
+**What counts against a limit.** Limits meter what leaves the owner's balance, not net exposure.
+A supply or a stake counts in full, and withdrawing or unstaking returns the funds without giving
+the allowance back. A supply-and-withdraw or stake-and-unstake cycle costs the allowance once, so
+size lending and staking limits for the cycles the agent will run, and tell the owner when they
+ask for something like "restake with a better validator".
+
+**Term and gas.** `days` is the agent's term, 1 to 30. `gasSui` (default 0.05) is a stipend sent
+to the agent key, outside the rules. `gasCapSui` (default 0.1) is a separate allowance the key
+draws on to top up its gas, and `gasDailySui` (default a fifth of `gasCapSui`) its daily limit.
+
+**What the owner needs.** Allowances draw only from the owner's address balance, never from coin
+objects. The review page reads both, and the signature converts coin objects into the address
+balance as far as each cap (plus `gasCapSui` for SUI) needs; the converted coins stay theirs. The
+owner needs that much in total, address balance and coin objects together, plus `gasSui` and fees.
+
+Before you call anything, show the owner the rules you intend to propose as one short list and
+ask for a yes, unless they already stated every rule explicitly.
+
+## 2. Propose the pass and wait for the signature
+
+`propose_authorization`, `propose_change`, `list_passes`, `revoke_pass` and `forget_pass` live on
+the stdio server (`agent-pass mcp`), which keeps every session on the machine. A per-session HTTP
+signer has only `session_info` and `sign_transaction`.
+
+The pass goes on the network the owner names (`network`, one of `list_passes.networks`), else on
+the first network listed. A private publish of one's own takes a `deployment` path instead.
+
+Call `propose_authorization` with the rules. It returns `rules`, the exact text the review page
+shows, plus `reviewUrl` and `sessionAddress`, and opens the page in the browser. Paste `rules` to
+the owner word for word and never restate the amounts yourself. Tell them to connect their wallet,
+check the page against that text and sign once. The page shows what their wallet holds against
+what the pass needs. If the browser did not open, give them `reviewUrl`.
+
+Then call `session_info` with the pass and `wait: 120`, again while the status is
+`awaiting_authorization`. At `active` the signer has read the pass, the allowances and the
+policies back from chain and checked them against the proposal. Report the pass id, the
+authorization digest, the owner's balances and what the key may still withdraw.
+
+## 3. Act within the rules
+
+Start with `session_info`. It returns:
+
+- `control`: the installed policies with today's usage, the held stakes and NAVI position;
+- `allowances`: what the key may still withdraw under each;
+- `ownerBalances`: per coin, `addressBalance` (what allowances draw from) and `coinBalance` (coin
+  objects only the owner can move), so a low address balance next to coin objects is not an owner
+  out of money;
+- `gas`: the agent key's own SUI;
+- `coins` and `venues`: each coin's type and decimals, and each pool with its pair, both
+  directions' entry functions and DeepBook's minimum order;
+- `directory`, `sdk` and `server`: the session directory, how to install and import the SDK,
+  and this server's version (after an upgrade the client must restart the server).
+
+Act by writing a Node script against the SDK. Run `sdk.install` once in your working directory,
+then:
+
+```ts
+import {
+	Agent,
+	borrow,
+	pickValidator,
+	quote,
+	repay,
+	send,
+	stake,
+	supply,
+	swap,
+	unstake,
+	withdraw,
+} from '@mysten-incubation/sui-agent-pass/agent';
+import { units } from '@mysten-incubation/sui-agent-pass/domain';
+
+const agent = await Agent.open(directory);
+const usdc = agent.identity.deployment.coins.find((c) => c.symbol === 'USDC')!;
+const out = await agent.submit(send(agent.identity, usdc.type, units('5', usdc.decimals), 'alice'));
+```
+
+**Swaps.** Before every swap, `quote(identity, pair, amountIn)` prices it on the venue without
+touching an allowance: `amountIn` is what the pool would take and `amountOut` what comes back.
+Set `minOut` a little under `amountOut`, never from a mid price; the owner's price limit still
+applies underneath. DeepBook takes its fee from the input and rounds down to its lot size, so
+sell at least one lot over its minimum.
+
+**Repayments.** Size a repayment from the live debt: an over-payment returns to the owner but
+still counts against the allowance.
+
+**Outcomes.** `submit` signs through this server, executes on Sui and returns what the chain
+recorded. `success: true` means done. `success: false` means the chain executed the transaction
+and refused it; `reason` is the owner's rule that stopped it, and you quote it. A thrown error
+means nothing executed (a dry run or client error), which you never describe as on-chain
+enforcement. `submit` tops up your gas from the gas allowance when it runs low.
+
+**Hand-built transactions.** For anything the builders do not cover, build the PTB with
+`@mysten/sui` following the guide, sign it with `sign_transaction` and execute it yourself. Every
+spend takes the allowance object and a withdrawal input right after the pass. On this path gas is
+yours: when the key holds under 0.01 SUI, draw on the gas allowance as the guide shows. That
+allowance has its own cap and daily limit and never touches the asset caps.
+
+## 4. Report the state
+
+Call `list_passes`, then `session_info` for each pass the owner asks about (all of them when
+unclear). Report the status (`awaiting_authorization`, `active`, `changing`, `expired`, `revoked`
+or `closed`), the owner's address balances, what the key may still withdraw, its gas, any NAVI
+position or stakes in the pass, and for each policy its limit and today's usage
+(`control.policies[*].usage.usedToday`). Quote the `rules` text as returned; do not recompute
+amounts.
+
+## 5. Change the rules
+
+When a limit, a recipient, a pool, a price or the term no longer fits, change the pass instead of
+proposing a new one. Call `propose_change` with the pass and the complete new rule set (every
+rule, not just the changed ones), in the same shape as `propose_authorization` without the name
+and the stipend. It opens the review page with the current rules beside the new ones; paste its
+`changes` text to the owner. One signature replaces the policies and reissues only the
+allowances whose cap or term changed. The agent key, its gas and what the pass holds stay;
+replaced policies start the day's usage at zero, and kept allowances keep their lifetime spend.
+
+Until the owner signs, the old rules apply and `session_info` reports `changing`. Poll it with
+`wait` until it is `active` again, then read the rules back before acting.
+
+## 6. End it
+
+There are two endings, both on the pass page, which `revoke_pass` opens for the pass the owner
+names. Without a pass it opens the owner page, which lists all of the owner's passes and ends any
+number of them with one signature; use that when several are to go.
+
+- **Stop the agent now** revokes the key and deletes the allowances, and keeps the pass and its
+  history on chain. It is the instant answer when something is wrong.
+- **Close the pass** does the same, then returns everything the pass holds to the owner's wallet
+  and deletes the pass, which refunds its storage deposit. A NAVI position that owes nothing is
+  withdrawn into the owner's wallet first, since NAVI's own app cannot operate a pass's position.
+  A position with debt is handed over as it is, and the owner page lists it with its balances.
+  This is the normal ending when the owner is done.
+
+Tell the owner both exist and that closing refunds the storage cost. They connect the wallet that
+created the pass, pick an ending and sign. Opening the page revokes nothing; only the signed
+transaction does. Then call `session_info` with `wait: 60` until the status is `revoked` or
+`closed`, and confirm that the chain now refuses the key. On a stopped pass, each held object has
+its own **Reclaim** button: a NAVI position comes back with its account cap (collateral first
+when it owes nothing), and a stake as an ordinary `StakedSui`.
+
+Once a pass is closed, the signer returns the key's unspent gas to the owner the next time it
+runs. Then call `forget_pass` for the session: it refuses while the pass is live, returns any gas
+still there, and deletes the session directory with its key. Offer it for every pass
+`list_passes` reports as closed or stopped, and for proposals the owner never signed.
+
+`list_passes` may also report `unreadable` sessions from an earlier version of this package.
+Their passes may still be live: tell the owner to stop or close each one from its pass page on
+the site, which reads the chain and needs no session file.
+
+## Rules of conduct
+
+- Confirm with the owner before the first transaction of a session and before any action they
+  did not explicitly ask for. Recurring work they asked for, such as a daily purchase, needs no
+  confirmation each time.
+- Save the digest of every submission. If a response times out, look the digest up before
+  retrying; never resubmit an action while the original could still execute.
+- Never search for, read or copy key files. `sign_transaction` is the only way to sign.
+- Report outcomes from chain state (`session_info`, the digest), never from a signature.