@mysten-incubation/sui-agent-pass 0.1.7 → 0.1.9

package/deployments/mainnet.json

@@ -35,12 +35,14 @@
 	"protocols": {
 		"deepbook": {
 			"packageId": "0x2c8d603bc51326b8c13cef9dd07031a408a48dddb541963357661df5d3204809",
-			"publishedAt": "0x0e735f8c93a95722efd73521aca7a7652c0bb71ed1daf41b26dfd7d1ff71f748"
+			"publishedAt": "0x0e735f8c93a95722efd73521aca7a7652c0bb71ed1daf41b26dfd7d1ff71f748",
+			"indexerUrl": "https://deepbook-indexer.mainnet.mystenlabs.com"
 		},
 		"cetus": {
 			"packageId": "0x1eabed72c53feb3805120a081dc15963c204dc8d091542592abaf7a35689b2fb",
 			"publishedAt": "0x260693ec785a6e6c9d81d58c7d2ff72f1288ae0fa6a9725abe05a6478b11f084",
-			"configId": "0xdaa46292632c3c4d8f31f23ea0f9b36a28ff3677e9684980e4438403a67a3d8f"
+			"configId": "0xdaa46292632c3c4d8f31f23ea0f9b36a28ff3677e9684980e4438403a67a3d8f",
+			"apiUrl": "https://api-sui.cetus.zone"
 		},
 		"navi": {
 			"packageId": "0x66c91a8560cd64d73d93dd1ec7b61f3f21ad2f66553dd3d7038ca69255479bb7",

package/dist/chain.js

@@ -661,6 +661,70 @@ export async function withMarketFacts(client, d, needs) {
     }
     return { ...d, coins, pools };
 }
+/**
+ * Pools on DeepBook and Cetus that trade `coin` (against `other` when given), largest Cetus TVL
+ * first. The venues' public listings only nominate candidates; each one is then read from chain
+ * by `withMarketFacts`, which drops anything that is not a pool of those coins. Returns the
+ * deployment extended with the pools and coins found.
+ */
+export async function findPools(client, d, coin, other) {
+    const want = normalizeStructTag(coin), with_ = other ? normalizeStructTag(other) : null;
+    const fits = (a, b) => {
+        const [x, y] = [normalizeStructTag(a), normalizeStructTag(b)];
+        return (x === want && (!with_ || y === with_)) || (y === want && (!with_ || x === with_));
+    };
+    const candidates = new Map();
+    for (const p of d.pools)
+        if (fits(p.coinA, p.coinB))
+            candidates.set(p.poolId, null);
+    const { deepbook, cetus } = d.protocols;
+    const listings = await Promise.all([
+        deepbook.indexerUrl
+            ? fetch(`${deepbook.indexerUrl}/get_pools`, { signal: AbortSignal.timeout(8_000) })
+                .then((r) => r.json())
+                .then((all) => all
+                .filter((p) => fits(p.base_asset_id, p.quote_asset_id))
+                .map((p) => [p.pool_id, null]))
+                .catch(() => [])
+            : [],
+        cetus.apiUrl
+            ? fetch(`${cetus.apiUrl}/v3/sui/clmm/stats_pools`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    filter: '',
+                    sortBy: 'tvl',
+                    sortOrder: 'desc',
+                    limit: 20,
+                    offset: 0,
+                    coinTypes: [want],
+                }),
+                signal: AbortSignal.timeout(8_000),
+            })
+                .then((r) => r.json())
+                .then((r) => (r.data?.list ?? [])
+                .filter((p) => fits(p.coinA.coinType, p.coinB.coinType))
+                .map((p) => [p.pool, p.tvl ?? null]))
+                .catch(() => [])
+            : [],
+    ]);
+    for (const [id, tvl] of listings.flat())
+        candidates.set(normalizeSuiAddress(id), tvl);
+    const ranked = [...candidates]
+        .sort(([, a], [, b]) => Number(b ?? 0) - Number(a ?? 0))
+        .slice(0, 10);
+    let extended = d;
+    const found = [];
+    for (const [id, tvl] of ranked) {
+        const next = await withMarketFacts(client, extended, { coins: [], pools: [id] }).catch(() => null);
+        const pool = next?.pools.find((p) => p.poolId === normalizeSuiAddress(id));
+        if (!next || !pool || !fits(pool.coinA, pool.coinB))
+            continue;
+        extended = next;
+        found.push({ pool, tvlUsd: tvl === null ? null : Number(tvl).toFixed(0) });
+    }
+    return { d: extended, found };
+}
 function structTagString(t) {
     const params = t.typeParams.map((p) => (typeof p === 'string' ? p : structTagString(p)));
     return `${t.address}::${t.module}::${t.name}${params.length ? `<${params.join(',')}>` : ''}`;

package/dist/domain.js

@@ -164,10 +164,20 @@ export const DeploymentSchema = z
             packageId: address,
             /** The latest upgrade, for calls made from a PTB; the original is version-gated. */
             publishedAt: address,
+            /** DeepBook's public indexer, which lists every pool; used only to find candidates. */
+            indexerUrl: z.string().url().optional(),
         })
             .strict(),
         /** `packageId` defines the pool type; `publishedAt` is the upgrade that answers calls. */
-        cetus: z.object({ packageId: address, publishedAt: address, configId: address }).strict(),
+        cetus: z
+            .object({
+            packageId: address,
+            publishedAt: address,
+            configId: address,
+            /** Cetus's public API, which lists pools by coin; used only to find candidates. */
+            apiUrl: z.string().url().optional(),
+        })
+            .strict(),
         navi: z
             .object({
             /** The package that defines `account::AccountCap`, which the pass holds. */

package/dist/mcp.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { clientFor, deepbookSizes, readAllHoldings, readStatus } from './chain.js';
-import { coinInfo } from './domain.js';
+import { coinInfo, DAY_MS } from './domain.js';
 export const result = (value) => ({
     content: [{ type: 'text', text: JSON.stringify(value) }],
 });
@@ -45,14 +45,51 @@ async function sdkInfo(directory) {
         note: published ? null : `${root} must be built (npm run build) before installing from it`,
     };
 }
-/** Which code answers: the package version and when it was built, so a stale server shows. */
-async function serverInfo() {
+let latest = null;
+/** The newest version on npm, asked at most once a day per process; null when npm is unreachable. */
+async function latestVersion(name) {
+    if (latest && Date.now() - latest.at < DAY_MS)
+        return latest.version;
+    const version = await fetch(`https://registry.npmjs.org/${name.replace('/', '%2F')}/latest`, {
+        signal: AbortSignal.timeout(2_000),
+    })
+        .then((r) => (r.ok ? r.json() : null))
+        .then((j) => j?.version ?? null)
+        .catch(() => null);
+    latest = { at: Date.now(), version };
+    return version;
+}
+const newer = (a, b) => {
+    const [x, y] = [a, b].map((v) => v.split('-')[0].split('.').map(Number));
+    for (let i = 0; i < 3; i++)
+        if (x[i] !== y[i])
+            return (x[i] ?? 0) > (y[i] ?? 0);
+    return false;
+};
+/**
+ * Which code answers: the package version and when it was built, so a stale server shows, and
+ * for an installed package a newer release on npm with the command that takes it.
+ */
+export async function serverInfo() {
     const pkg = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
     const built = await stat(fileURLToPath(import.meta.url)).then((s) => s.mtime.toISOString());
+    const installed = fileURLToPath(import.meta.url)
+        .split(sep)
+        .includes('node_modules');
+    const available = installed ? await latestVersion(pkg.name) : null;
     return {
         version: pkg.version,
         builtAt: built,
         note: 'This process keeps the code it started with. After this package is rebuilt or upgraded, restart the agent client so it starts a new server; compare builtAt.',
+        ...(available && newer(available, pkg.version)
+            ? {
+                update: {
+                    latest: available,
+                    command: `npm install -g ${pkg.name}@latest`,
+                    then: 'Restart the agent client so it starts the new server; the agent-pass skill is linked to the package and follows it.',
+                },
+            }
+            : {}),
     };
 }
 /**

package/dist/plugin.js

@@ -20,12 +20,12 @@ 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, readAllHoldings, readStatus, withMarketFacts, } from './chain.js';
+import { clientFor, deepbookSizes, findPools, 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';
 import { passEnded, returnGasFloat } from './float.js';
-import { failure, INSTRUCTIONS, registerDocs, result, sessionInfo, SIGN_ANNOTATIONS, SIGN_DESCRIPTION, } from './mcp.js';
+import { failure, INSTRUCTIONS, registerDocs, result, serverInfo, sessionInfo, SIGN_ANNOTATIONS, SIGN_DESCRIPTION, } from './mcp.js';
 import { authenticated, body, ownerPageUrl, startServer } from './server.js';
 import { SessionSigner } from './signer.js';
 import { SessionStore, token } from './storage.js';
@@ -233,7 +233,7 @@ const rulesInput = {
         pools: z
             .array(address)
             .optional()
-            .describe('pool object ids for a pair the deployment does not list (a DeepBook or Cetus pool holding exactly these two coins); verified on chain'),
+            .describe('pool ids from find_pools for a pair the network does not list; never ask the owner for one. Verified on chain'),
         perTrade: decimal.describe('sold coin per trade'),
         daily: decimal.describe('sold coin per UTC day'),
         limitPrice: decimal.describe("the owner's price limit. With a stablecoin on one side it is that stablecoin per one of the other coin: the most paid when buying, the least accepted when selling. Otherwise it is bought coin per one sold coin, the least accepted. Required, above 0, and only the owner sets it: ask them, showing the pool's current price from list_passes"),
@@ -311,7 +311,7 @@ async function toSetup(client, d0, input) {
                     (!sw.pools || sw.pools.some((id) => normalizeSuiAddress(id) === p.poolId)));
                 if (!pools.length)
                     throw new Error(d.pools.length
-                        ? `No pool trades ${sw.sell} for ${sw.buy}${sw.venues ? ` on ${sw.venues.join(', ')}` : ''}${sw.pools ? ` among ${sw.pools.join(', ')}` : ''}; name a DeepBook or Cetus pool id for this pair in pools`
+                        ? `No pool trades ${sw.sell} for ${sw.buy}${sw.venues ? ` on ${sw.venues.join(', ')}` : ''}${sw.pools ? ` among ${sw.pools.join(', ')}` : ''}; look one up with find_pools and pass its id in pools`
                         : `Swaps are not offered on ${d.network}: it lists no pools. Propose a pass on a network that does, or leave swaps out`);
                 return {
                     coinIn,
@@ -405,6 +405,20 @@ export async function forgetSession(directory) {
     await registry.all();
     return registry.forget(basename(resolve(directory)));
 }
+/**
+ * What a 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.
+ */
+async function poolPrice(d, p) {
+    const flip = isStable(coinInfo(d, p.coinA).symbol) && !isStable(coinInfo(d, p.coinB).symbol);
+    const a = coinInfo(d, flip ? p.coinB : p.coinA), b = coinInfo(d, flip ? p.coinA : p.coinB);
+    const amountIn = (10n * 10n ** BigInt(a.decimals)).toString();
+    const q = await quoteSwap(clientFor(d), d, p, a.type, amountIn).catch(() => null);
+    if (!q || q.amountOut === '0')
+        return {};
+    const perUnit = (BigInt(q.amountOut) * 10n ** BigInt(a.decimals)) / BigInt(q.amountIn);
+    return { price: `${display(perUnit.toString(), b.decimals)} ${b.symbol} per ${a.symbol}` };
+}
 export function createPluginMcp(registry) {
     const server = new McpServer({ name: 'agent-pass', version: '0.1.0' }, {
         instructions: `${INSTRUCTIONS} This server also runs the owner flow: propose_authorization turns reviewed rules into a pass proposal and opens the owner's wallet page; session_info (with wait) reports when the owner has signed and the on-chain policies match; revoke_pass reopens the owner page for revocation. Show the owner the exact "rules" text returned by propose_authorization before they sign; never paraphrase amounts.`,
@@ -420,30 +434,18 @@ export function createPluginMcp(registry) {
         annotations: { readOnlyHint: true },
     }, 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.
-        const price = async (d, p) => {
-            const flip = isStable(coinInfo(d, p.coinA).symbol) && !isStable(coinInfo(d, p.coinB).symbol);
-            const a = coinInfo(d, flip ? p.coinB : p.coinA), b = coinInfo(d, flip ? p.coinA : p.coinB);
-            const amountIn = (10n * 10n ** BigInt(a.decimals)).toString();
-            const q = await quoteSwap(clientFor(d), d, p, a.type, amountIn).catch(() => null);
-            if (!q || q.amountOut === '0')
-                return {};
-            const perUnit = (BigInt(q.amountOut) * 10n ** BigInt(a.decimals)) / BigInt(q.amountIn);
-            return { price: `${display(perUnit.toString(), b.decimals)} ${b.symbol} per ${a.symbol}` };
-        };
         const markets = async (d) => ({
             network: d.network,
             coins: d.coins,
             pools: await Promise.all(d.pools.map(async (p) => ({
                 venue: p.venue,
                 pair: `${coinInfo(d, p.coinA).symbol}/${coinInfo(d, p.coinB).symbol}`,
-                ...(await price(d, p)),
+                ...(await poolPrice(d, p)),
             }))),
             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.',
+                    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; for a swap, find_pools looks up the DeepBook and Cetus pools for it, and their ids go in pools. Never ask the owner for a pool id. 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.',
@@ -465,11 +467,44 @@ export function createPluginMcp(registry) {
                 }
                 : {}),
             deployment: { path, exists: own.length > 0 },
+            server: await serverInfo(),
             networks: [...own, ...bundled.filter((b) => !own.some((o) => o.network === b.network))],
         });
     });
+    server.registerTool('find_pools', {
+        description: "Find the DeepBook and Cetus pools that trade a coin, optionally against one other coin, for a swap rule. Each result is read from chain and carries its venue, id, pair, both coin types, Cetus TVL in USD when known and the pool's current price. Use it instead of asking the owner for a pool; prefer the deepest pool, and when the coin is ambiguous show the owner their balance of it and this price so they can confirm it is the right token.",
+        inputSchema: {
+            coin: symbol.describe('the coin, by symbol when list_passes lists it, else by full type'),
+            with: symbol.optional().describe('the other coin of the pair, same form; any when omitted'),
+            network: z
+                .enum(['mainnet', 'testnet', 'devnet', 'localnet'])
+                .optional()
+                .describe('defaults to the network a new pass would use'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ coin, with: other, network }) => {
+        try {
+            const d0 = await registry.deployment(undefined, network);
+            const type = (s) => (/::/.test(s) ? s : coinBySymbol(d0, s).type);
+            const { d, found } = await findPools(clientFor(d0), d0, type(coin), other ? type(other) : undefined);
+            const priced = await Promise.all(found.map(async ({ pool, tvlUsd }) => ({
+                venue: pool.venue,
+                poolId: pool.poolId,
+                pair: `${coinInfo(d, pool.coinA).symbol}/${coinInfo(d, pool.coinB).symbol}`,
+                coinA: pool.coinA,
+                coinB: pool.coinB,
+                tvlUsd,
+                ...(await poolPrice(d, pool)),
+            })));
+            // A pool that cannot price ten units holds too little to trade against.
+            return result({ network: d.network, pools: priced.filter((p) => 'price' in p) });
+        }
+        catch (error) {
+            return failure(error, 'Pool lookup failed');
+        }
+    });
     server.registerTool('propose_authorization', {
-        description: "Create a new pass proposal from rules in human units (coins by symbol when list_passes lists them for the network, else by full type, with pool ids for a pair the network list lacks; amounts as decimal strings) and open the owner's review page, where they connect Slush, check the same rules and sign one transaction. That transaction creates the pass, converts the owner's coins into their own address balance as far as the caps need, issues the allowances the agent will draw on, installs the policies and gives the new agent key its gas; the owner's coins never enter the pass. Returns the exact rules text to show the owner, the review URL and the session address. Nothing is on chain until the owner signs; poll session_info with wait afterwards.",
+        description: "Create a new pass proposal from rules in human units (coins by symbol when list_passes lists them for the network, else by full type, with pool ids from find_pools for a pair the network list lacks; amounts as decimal strings) and open the owner's review page, where they connect Slush, check the same rules and sign one transaction. That transaction creates the pass, converts the owner's coins into their own address balance as far as the caps need, issues the allowances the agent will draw on, installs the policies and gives the new agent key its gas; the owner's coins never enter the pass. Returns the exact rules text to show the owner, the review URL and the session address. Nothing is on chain until the owner signs; poll session_info with wait afterwards.",
         inputSchema: {
             name: z
                 .string()

package/docs/PLAYBOOK.md

@@ -54,14 +54,17 @@ pool), so list Cetus as well when trades will be small. A network may list no po
 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.
+package lists, not the only ones it can use. Name a listed coin by symbol, and any other coin the
+owner holds by its full type. To find its type and balance, ask the owner for their address and
+call `list_passes` with `owner`: it adds every coin that address holds per network. For a swap,
+find the pool with `find_pools`, which looks up DeepBook and Cetus, reads each pool from chain and
+quotes its current price; pick the deepest one for the pair and pass its id in `pools`. Never ask
+the owner for a pool id. When you are unsure you have the right token (several coins share a
+symbol, or the owner named it loosely), show the owner their balance of it and its current price
+and ask them to confirm. The server and the review page read a coin's symbol and decimals and 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
@@ -89,9 +92,9 @@ 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`.
+`propose_authorization`, `propose_change`, `list_passes`, `find_pools`, `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.
@@ -122,6 +125,10 @@ Start with `session_info`. It returns:
 - `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).
 
+**Updates.** When `server.update` is present in `list_passes` or `session_info`, a newer release
+is out. Tell the owner once per conversation, with `server.update.command` and the reminder to
+restart the agent afterwards, then carry on with the task; never run the command yourself.
+
 Act by writing a Node script against the SDK. Run `sdk.install` once in your working directory,
 then:
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mysten-incubation/sui-agent-pass",
-	"version": "0.1.7",
+	"version": "0.1.9",
 	"type": "module",
 	"description": "AI builds transactions. A session signer signs. Your pass enforces the rules.",
 	"repository": {

package/skills/agent-pass/SKILL.md

@@ -59,14 +59,17 @@ pool), so list Cetus as well when trades will be small. A network may list no po
 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.
+package lists, not the only ones it can use. Name a listed coin by symbol, and any other coin the
+owner holds by its full type. To find its type and balance, ask the owner for their address and
+call `list_passes` with `owner`: it adds every coin that address holds per network. For a swap,
+find the pool with `find_pools`, which looks up DeepBook and Cetus, reads each pool from chain and
+quotes its current price; pick the deepest one for the pair and pass its id in `pools`. Never ask
+the owner for a pool id. When you are unsure you have the right token (several coins share a
+symbol, or the owner named it loosely), show the owner their balance of it and its current price
+and ask them to confirm. The server and the review page read a coin's symbol and decimals and 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
@@ -94,9 +97,9 @@ 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`.
+`propose_authorization`, `propose_change`, `list_passes`, `find_pools`, `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.
@@ -127,6 +130,10 @@ Start with `session_info`. It returns:
 - `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).
 
+**Updates.** When `server.update` is present in `list_passes` or `session_info`, a newer release
+is out. Tell the owner once per conversation, with `server.update.command` and the reminder to
+restart the agent afterwards, then carry on with the task; never run the command yourself.
+
 Act by writing a Node script against the SDK. Run `sdk.install` once in your working directory,
 then: