@mysten-incubation/sui-agent-pass 0.0.0 → 0.1.0

package/dist/plugin.js

@@ -0,0 +1,795 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The Claude Code plugin's MCP: one stdio process that proposes passes for the owner to sign
+ * in the browser, reports their state, signs the agent's transactions and opens the owner
+ * page for revocation. Owner consent stays in the browser; this process never builds an
+ * agent transaction and never holds an owner key.
+ */
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { access, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { Transaction } from '@mysten/sui/transactions';
+import { fromBase64, normalizeSuiAddress } from '@mysten/sui/utils';
+import { z } from 'zod';
+import { clientFor, deepbookSizes, readStatus, withMarketFacts } from './chain.js';
+import { describePolicy, describeSetup, renderRows } from './describe.js';
+import { address, coinBySymbol, coinInfo, DAY_MS, defaultGasDaily, DeploymentSchema, display, poolsFor, priceUnits, 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 { authenticated, body, ownerPageUrl, startServer } from './server.js';
+import { SessionSigner } from './signer.js';
+import { SessionStore, token } from './storage.js';
+export const defaultRoot = () => join(homedir(), '.sui-agent-pass');
+export function openBrowser(url) {
+    spawn(process.platform === 'darwin' ? 'open' : 'xdg-open', [url], {
+        stdio: 'ignore',
+    }).on('error', () => { });
+}
+const repoRoot = fileURLToPath(new URL('..', import.meta.url));
+/**
+ * How to start this CLI again from another process: the compiled entry under node, or, when
+ * running from source through tsx, the source entry through tsx.
+ */
+export function cliInvocation() {
+    const entry = fileURLToPath(new URL('./cli.js', import.meta.url));
+    return entry.endsWith('.js') && !import.meta.url.endsWith('.ts')
+        ? [process.execPath, entry]
+        : [join(repoRoot, 'node_modules/.bin/tsx'), entry.replace(/\.js$/, '.ts')];
+}
+const exists = (path) => access(path).then(() => true, () => false);
+/** Every session directory under the root, opened lazily and kept for the process lifetime. */
+class Registry {
+    options;
+    sessions = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    get sessionsDir() {
+        return join(this.options.root, 'sessions');
+    }
+    /** Sessions on disk this code cannot open, with what their files still say about the pass. */
+    unreadable = new Map();
+    async all() {
+        await mkdir(this.sessionsDir, { recursive: true, mode: 0o700 });
+        for (const id of (await readdir(this.sessionsDir)).sort()) {
+            if (this.sessions.has(id))
+                continue;
+            try {
+                this.sessions.set(id, {
+                    id,
+                    store: await SessionStore.open(join(this.sessionsDir, id), (network, packageId) => this.current(network, packageId)),
+                });
+                this.unreadable.delete(id);
+            }
+            catch (error) {
+                // An earlier state version or a damaged file: listed as unreadable, never fatal, since
+                // its pass may still be live on chain and the site can close it from there.
+                this.unreadable.set(id, {
+                    id,
+                    problem: error.message,
+                    ...(await SessionStore.peek(join(this.sessionsDir, id))),
+                });
+            }
+        }
+        return [...this.sessions.values()];
+    }
+    /** By id prefix, pass object id prefix, or the only sensible candidate. */
+    async find(selector) {
+        const all = await this.all();
+        if (selector) {
+            const wanted = selector.toLowerCase();
+            const hits = all.filter((s) => s.id.startsWith(wanted) || s.store.state.active?.passId.startsWith(wanted));
+            if (hits.length === 1)
+                return hits[0];
+            throw new Error(hits.length
+                ? `Several passes match ${selector}; use a longer id`
+                : `No pass matches ${selector}; call list_passes`);
+        }
+        if (all.length === 1)
+            return all[0];
+        const active = all.filter((s) => s.store.state.active);
+        if (active.length === 1)
+            return active[0];
+        throw new Error(all.length
+            ? 'Several passes exist; pass the pass id from list_passes'
+            : 'No pass yet; call propose_authorization first');
+    }
+    async create(deployment, setup) {
+        await mkdir(this.sessionsDir, { recursive: true, mode: 0o700 });
+        const id = randomUUID();
+        const session = {
+            id,
+            store: await SessionStore.create(join(this.sessionsDir, id), deployment, setup),
+        };
+        this.sessions.set(id, session);
+        return session;
+    }
+    /** The owner page and per-session HTTP signer, started on first use. */
+    async server(session) {
+        if (!session.server) {
+            session.server = await startServer(session.store);
+            // A watcher (a recorder, a second pane) can point at the review page without the token
+            // passing through the model. Same directory and mode as mcp.token.
+            await writeFile(join(session.store.directory, 'owner-url.txt'), session.server.ownerUrl + '\n', { mode: 0o600 });
+        }
+        return session.server;
+    }
+    async signer(session) {
+        session.signer ??= new SessionSigner(await session.store.key(), session.store.state.deployment.chainIdentifier);
+        return session.signer;
+    }
+    async close() {
+        await Promise.all([...this.sessions.values()].map((s) => s.server?.close()));
+    }
+    deploymentPath(override) {
+        return resolve(override ?? this.options.deployment ?? join(this.options.root, 'deployment.json'));
+    }
+    /** The networks this package ships a deployment for, in the order a new pass defaults to. */
+    async bundledNetworks() {
+        const all = ['mainnet', 'testnet', 'devnet'];
+        const present = await Promise.all(all.map((n) => exists(this.bundledPath(n))));
+        return all.filter((_, i) => present[i]);
+    }
+    bundledPath(network) {
+        return fileURLToPath(new URL(`../deployments/${network}.json`, import.meta.url));
+    }
+    /** Today's deployment for a network when it is the same package: the private file first, else the bundled one. */
+    async current(network, packageId) {
+        const candidates = [
+            () => this.deployment().catch(() => null),
+            () => this.bundled(network).catch(() => null),
+        ];
+        for (const read of candidates) {
+            const d = await read();
+            if (d &&
+                d.network === network &&
+                normalizeSuiAddress(d.packageId) === normalizeSuiAddress(packageId))
+                return d;
+        }
+        return null;
+    }
+    /**
+     * Retires a session directory once its pass is over: refuses while the pass is live, returns
+     * the key's gas float to the owner first, then deletes the directory and its key. Works on a
+     * session this code cannot open (an earlier state version), from what its file still says.
+     */
+    async forget(id) {
+        const dir = join(this.sessionsDir, id);
+        const session = this.sessions.get(id);
+        const peek = await SessionStore.peek(dir);
+        const d = session?.store.state.deployment ??
+            (peek.network && peek.packageId ? await this.current(peek.network, peek.packageId) : null);
+        if (peek.passId) {
+            if (!d)
+                throw new Error('No deployment known for this session; cannot tell whether its pass is live');
+            if (!(await passEnded(clientFor(d), d, peek.passId)))
+                throw new Error('This pass is live; stop or close it from its page first');
+        }
+        let swept = null;
+        if (peek.passId && peek.owner && peek.sessionAddress && d)
+            swept = await returnGasFloat(clientFor(d), dir, peek.sessionAddress, peek.owner);
+        await session?.server?.close();
+        this.sessions.delete(id);
+        this.unreadable.delete(id);
+        await SessionStore.forget(dir);
+        return { swept };
+    }
+    async bundled(network) {
+        return DeploymentSchema.parse(JSON.parse(await readFile(this.bundledPath(network), 'utf8')));
+    }
+    /**
+     * Where a new pass goes: an explicit file, else the private `deployment.json` under the root
+     * (a publish of one's own), else the deployment bundled for `network`, else the first bundled
+     * one. A user who installed the package has only the bundled ones and needs no file.
+     */
+    async deployment(override, network) {
+        const configured = this.deploymentPath(override);
+        if (override || this.options.deployment || (await exists(configured)))
+            return DeploymentSchema.parse(JSON.parse(await readFile(configured, 'utf8')));
+        const bundled = await this.bundledNetworks();
+        const chosen = network ?? bundled[0];
+        if (!chosen || !(network === undefined || bundled.includes(network)))
+            throw new Error(`No deployment for ${network ?? 'any network'}: this package ships ${bundled.join(', ') || 'none'}, and there is no ${configured}.`);
+        return this.bundled(chosen);
+    }
+}
+const decimal = z.string().regex(/^[0-9]+(\.[0-9]+)?$/, 'decimal number');
+const symbol = z
+    .string()
+    .min(1)
+    .max(120)
+    .describe('a coin: its symbol when list_passes lists it for the network (e.g. SUI), otherwise its full type (0x…::module::NAME); the page then reads its metadata from chain');
+const rulesInput = {
+    transfers: z
+        .array(z
+        .object({
+        coin: symbol,
+        recipients: z.array(z.object({ name: recipientName, address }).strict()).min(1),
+        perTransfer: decimal.describe('coin per transfer'),
+        daily: decimal.describe('coin per UTC day'),
+    })
+        .strict())
+        .default([])
+        .describe('one rule per coin the agent may pay out; empty forbids transfers'),
+    swaps: z
+        .array(z
+        .object({
+        sell: symbol,
+        buy: symbol,
+        venues: z
+            .array(VenueSchema)
+            .optional()
+            .describe('which listed pools for the pair; omit for every pool the deployment lists'),
+        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'),
+        perTrade: decimal.describe('sold coin per trade'),
+        daily: decimal.describe('sold coin per UTC day'),
+        minPrice: decimal.describe('lowest price accepted, in bought coin per one sold coin; required, above 0'),
+    })
+        .strict())
+        .default([])
+        .describe('one rule per direction the agent may trade; empty forbids swaps'),
+    lending: z
+        .array(z
+        .object({
+        coin: symbol,
+        allowBorrow: z
+            .boolean()
+            .describe('may also borrow and repay this coin, not only supply and withdraw it'),
+        perAction: decimal.describe('coin moved per action'),
+        daily: decimal.describe('coin moved per UTC day'),
+        minHealthFactor: z
+            .number()
+            .min(1)
+            .max(100)
+            .nullable()
+            .describe('withdraws and borrows keep the NAVI health factor above this; null for no floor'),
+    })
+        .strict())
+        .default([])
+        .describe('one rule per coin the agent may lend on NAVI; empty forbids lending'),
+    staking: z
+        .object({
+        validators: z
+            .array(address)
+            .describe('validator addresses the agent may stake with; empty = any active validator'),
+        perStake: decimal.describe('SUI per stake; the system minimum is 1'),
+        daily: decimal.describe('SUI staked per UTC day'),
+    })
+        .strict()
+        .nullable()
+        .default(null)
+        .describe('null forbids staking'),
+    caps: z
+        .record(symbol, decimal)
+        .describe("lifetime cap per coin the rules spend, by symbol: the most the agent may ever withdraw of it from the owner's address balance; the review page converts the owner's coins into that balance as far as the caps need. Exactly the spent coins, no others"),
+};
+/**
+ * Human amounts and coin names from the conversation become the exact base units and types the
+ * chain will store. A coin outside the deployment's list is named by type and its decimals come
+ * from chain metadata; a pool outside the list is named by id and its venue and coin order from
+ * its object. Returns the deployment extended with those facts, which the session keeps.
+ */
+async function toSetup(client, d0, input) {
+    const isType = (s) => /::/.test(s);
+    const named = [
+        ...input.transfers.map((t) => t.coin),
+        ...input.swaps.flatMap((sw) => [sw.sell, sw.buy]),
+        ...input.lending.map((l) => l.coin),
+        ...Object.keys(input.caps),
+    ];
+    const d = await withMarketFacts(client, d0, {
+        coins: named.filter(isType),
+        pools: input.swaps.flatMap((sw) => sw.pools ?? []),
+    });
+    const coin = (s) => (isType(s) ? coinInfo(d, s) : coinBySymbol(d, s)), inUnits = (s, v) => units(v, coin(s).decimals), sui = (v) => units(v, 9);
+    const ttlMs = input.days * DAY_MS, gasCap = sui(input.gasCapSui);
+    const setup = SetupSchema.parse({
+        name: input.name,
+        policy: {
+            transfers: input.transfers.map((t) => ({
+                coin: coin(t.coin).type,
+                recipients: t.recipients,
+                perTransfer: inUnits(t.coin, t.perTransfer),
+                daily: inUnits(t.coin, t.daily),
+            })),
+            swaps: input.swaps.map((sw) => {
+                const coinIn = coin(sw.sell).type, coinOut = coin(sw.buy).type;
+                const pools = poolsFor(d, coinIn, coinOut).filter((p) => (!sw.venues || sw.venues.includes(p.venue)) &&
+                    (!sw.pools || sw.pools.some((id) => normalizeSuiAddress(id) === p.poolId)));
+                if (!pools.length)
+                    throw new Error(`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`);
+                return {
+                    coinIn,
+                    coinOut,
+                    pools: pools.map((p) => p.poolId),
+                    perTrade: inUnits(sw.sell, sw.perTrade),
+                    daily: inUnits(sw.sell, sw.daily),
+                    minPrice: priceUnits(d, coinIn, coinOut, sw.minPrice),
+                };
+            }),
+            lending: input.lending.map((l) => ({
+                coin: coin(l.coin).type,
+                allowBorrow: l.allowBorrow,
+                perAction: inUnits(l.coin, l.perAction),
+                daily: inUnits(l.coin, l.daily),
+                minHealthFactor: l.minHealthFactor,
+            })),
+            staking: input.staking && {
+                validators: input.staking.validators,
+                perStake: sui(input.staking.perStake),
+                daily: sui(input.staking.daily),
+            },
+        },
+        ttlMs,
+        expiresMs: Date.now() + ttlMs,
+        allowances: Object.fromEntries(Object.entries(input.caps).map(([s, v]) => [coin(s).type, inUnits(s, v)])),
+        gasAmount: sui(input.gasSui),
+        gasCap,
+        gasDaily: input.gasDailySui ? sui(input.gasDailySui) : defaultGasDaily(gasCap),
+    });
+    return { setup, d };
+}
+function summary(s) {
+    const { state } = s.store;
+    return {
+        pass: s.id,
+        name: state.setup.name,
+        network: state.deployment.network,
+        sessionAddress: state.sessionAddress,
+        authorized: !!state.active,
+        passId: state.active?.passId ?? null,
+        directory: s.store.directory,
+    };
+}
+/**
+ * The summary plus what the chain says about the key: every pass created for it. A key is
+ * meant to sign one authorization, so a second pass here is a proposal signed twice, live on
+ * chain with its own allowances, which the session file knows nothing about.
+ */
+async function summaryWithChain(s) {
+    const base = summary(s), { state } = s.store, client = clientFor(state.deployment);
+    const created = await passesByAgent(client, state.deployment, state.sessionAddress).catch(() => null);
+    // A creation record outlives the pass; only an existing object is a live pass.
+    const onChain = created
+        ? await Promise.all(created.map(async (c) => ({
+            id: c.id,
+            live: await client.getObject({ objectId: c.id }).then(() => true, () => false),
+        })))
+        : null;
+    const own = onChain?.find((c) => c.id === state.active?.passId);
+    const closed = !!state.active && !!onChain && !own?.live;
+    const extra = onChain?.filter((c) => c.live && c.id !== state.active?.passId) ?? [];
+    return {
+        ...base,
+        ...(closed
+            ? {
+                status: 'closed',
+                note: 'The owner closed this pass; its key has nothing left to act on.',
+            }
+            : {}),
+        passesOnChain: onChain,
+        ...(extra.length
+            ? {
+                warning: `This key is the agent of ${extra.length + (own?.live ? 1 : 0)} live passes, not one: ${extra
+                    .map((c) => c.id)
+                    .join(', ')} were created by signing the same proposal again. Each is live with its own allowances and gas until the owner stops or closes it from its pass page (#/pass/<id>).`,
+            }
+            : {}),
+    };
+}
+/** `forget_pass` for one session directory, from outside the MCP: the CLI and tests. */
+export async function forgetSession(directory) {
+    const registry = new Registry({ root: dirname(dirname(resolve(directory))) });
+    await registry.all();
+    return registry.forget(basename(resolve(directory)));
+}
+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.`,
+    });
+    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: {},
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        const path = registry.deploymentPath();
+        const markets = async (d) => ({
+            network: d.network,
+            coins: d.coins,
+            pools: d.pools.map((p) => ({
+                venue: p.venue,
+                pair: `${coinInfo(d, p.coinA).symbol}/${coinInfo(d, p.coinB).symbol}`,
+            })),
+            lending: Object.keys(d.protocols.navi.reserves).map((c) => coinInfo(d, c).symbol),
+        });
+        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))));
+        const passes = await Promise.all((await registry.all()).map(summaryWithChain));
+        const unreadable = [...registry.unreadable.values()];
+        return result({
+            passes,
+            ...(unreadable.length
+                ? {
+                    unreadable,
+                    unreadableNote: 'These sessions were written by an earlier version of this package and cannot be used from here. Their passes may still be live: tell the owner, and have them stop or close each one from the pass page of the site (#/pass/<passId>), which reads the chain and needs no session file.',
+                }
+                : {}),
+            deployment: { path, exists: own.length > 0 },
+            networks: [...own, ...bundled.filter((b) => !own.some((o) => o.network === b.network))],
+        });
+    });
+    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.",
+        inputSchema: {
+            name: z
+                .string()
+                .regex(/^[\x20-\x7e]{1,64}$/)
+                .default('Agent session'),
+            ...rulesInput,
+            days: z.number().int().min(1).max(30).describe('agent term'),
+            gasSui: decimal
+                .default('0.05')
+                .describe('gas stipend to the agent address, outside the rules'),
+            gasCapSui: decimal
+                .default('0.1')
+                .describe('lifetime SUI the agent may pull to top up its gas, a separate allowance'),
+            gasDailySui: decimal
+                .optional()
+                .describe('SUI the agent may pull for gas per UTC day; defaults to a fifth of gasCapSui'),
+            network: z
+                .enum(['mainnet', 'testnet', 'devnet', 'localnet'])
+                .optional()
+                .describe('which network the pass lives on, from the deployments this package ships; omit for the default (a private deployment.json under the root, else the first shipped network)'),
+            deployment: z
+                .string()
+                .optional()
+                .describe('path of a private deployment.json; overrides network'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async ({ deployment, network, ...input }) => {
+        try {
+            const d0 = await registry.deployment(deployment, network);
+            const { setup, d } = await toSetup(clientFor(d0), d0, input);
+            const session = await registry.create(d, setup);
+            const { ownerUrl } = await registry.server(session);
+            if (registry.options.openBrowser !== false)
+                openBrowser(ownerUrl);
+            const rows = describeSetup(d, setup);
+            const warnings = [];
+            for (const sw of setup.policy.swaps) {
+                const pools = d.pools.filter((p) => sw.pools.includes(p.poolId));
+                if (pools.some((p) => p.venue === 'cetus'))
+                    continue;
+                for (const pool of pools.filter((p) => p.venue === 'deepbook')) {
+                    if (!sameCoin(pool.coinA, sw.coinIn))
+                        continue;
+                    // The fee comes off the input before the lot rounding, so the usable minimum is one
+                    // lot above the pool's.
+                    const floor = await deepbookSizes(clientFor(d), d, pool)
+                        .then((x) => (BigInt(x.minSize) + BigInt(x.lotSize)).toString())
+                        .catch(() => null);
+                    if (floor && BigInt(sw.perTrade) < BigInt(floor))
+                        warnings.push(`DeepBook takes its fee from the input and fills nothing under its minimum order, so a sale needs at least ${showCoin(d, sw.coinIn, floor)} and this pass allows ${showCoin(d, sw.coinIn, sw.perTrade)}: no sale could ever happen. Propose again with Cetus added to venues or a larger perTrade, unless the owner wants exactly this.`);
+                }
+            }
+            return result({
+                pass: session.id,
+                sessionAddress: session.store.state.sessionAddress,
+                reviewUrl: ownerUrl,
+                network: d.network,
+                rules: renderRows(rows),
+                rows,
+                warnings,
+                next: "The review page opened in the owner's browser (open reviewUrl if it did not). The owner connects Slush, compares the rules with the text above and signs. Then call session_info with this pass id and wait until it reports authorized.",
+            });
+        }
+        catch (error) {
+            return failure(error, 'Proposal failed');
+        }
+    });
+    server.registerTool('session_info', {
+        description: "Read one pass session: before authorization, the pending rules and review URL (pass wait to block up to 120 seconds for the owner's signature); afterwards the deployment, session address, installed policies with today's usage, the owner's balances and allowances, agent term, venue directions, the session directory and the SDK install command. Act with a Node script against the SDK (Agent.open(directory), then submit a builder's transaction), or build your own PTB and call sign_transaction, then submit to Sui yourself.",
+        inputSchema: {
+            pass: z
+                .string()
+                .optional()
+                .describe('pass id prefix from list_passes; omit if there is one'),
+            wait: z
+                .number()
+                .int()
+                .min(0)
+                .max(120)
+                .default(0)
+                .describe('seconds to wait for authorization'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ pass, wait }) => {
+        try {
+            const session = await registry.find(pass);
+            const { store } = session, { setup, deployment: d } = store.state;
+            const deadline = Date.now() + wait * 1000;
+            for (;;) {
+                await store.refresh();
+                if ((store.state.active && !store.state.pendingChange) || Date.now() >= deadline)
+                    break;
+                await sleep(1000);
+            }
+            if (!store.state.active) {
+                const { ownerUrl } = await registry.server(session);
+                return result({
+                    ...summary(session),
+                    status: 'awaiting_authorization',
+                    reviewUrl: ownerUrl,
+                    rules: renderRows(describeSetup(d, setup)),
+                });
+            }
+            const { mcpUrl } = await registry.server(session);
+            const exists = await clientFor(d)
+                .getObject({ objectId: store.state.active.passId })
+                .then(() => true, () => false);
+            if (!exists)
+                return result({
+                    ...summary(session),
+                    status: 'closed',
+                    note: 'The owner closed this pass: the object, its policies and allowances are gone and the storage deposit was refunded. The key has nothing left to act on.',
+                });
+            const info = await sessionInfo({
+                deployment: d,
+                sessionAddress: store.state.sessionAddress,
+                active: store.state.active,
+            }, store.directory);
+            const expired = Number(info.control.agentExpiresMs) <= info.control.chainTimeMs;
+            const pending = store.state.pendingChange;
+            return result({
+                ...summary(session),
+                status: info.revoked ? 'revoked' : expired ? 'expired' : pending ? 'changing' : 'active',
+                rules: renderRows(describePolicy(d, store.state.setup.policy, info.control.policies)),
+                ...(pending
+                    ? {
+                        proposedRules: renderRows(describeSetup(d, pending)),
+                        note: 'A rule change awaits the owner on the review page; the rules above are the ones in force.',
+                    }
+                    : {}),
+                ...info,
+                mcpUrl,
+            });
+        }
+        catch (error) {
+            return failure(error, 'Status unavailable');
+        }
+    });
+    server.registerTool('sign_transaction', {
+        description: `${SIGN_DESCRIPTION} The signing key is chosen by the transaction's sender, which must be the session address of an authorized pass.`,
+        inputSchema: { transactionBytes: z.string().min(1).max(180_000) },
+        annotations: SIGN_ANNOTATIONS,
+    }, async ({ transactionBytes }) => {
+        try {
+            const sender = Transaction.from(fromBase64(transactionBytes)).getData().sender;
+            if (!sender)
+                throw new Error('Transaction has no sender');
+            const session = (await registry.all()).find((s) => s.store.state.sessionAddress === normalizeSuiAddress(sender));
+            if (!session)
+                throw new Error('Sender is not the session address of any pass');
+            if (!session.store.state.active)
+                throw new Error('The owner has not authorized this pass yet');
+            return result(await (await registry.signer(session)).sign(transactionBytes));
+        }
+        catch (error) {
+            return failure(error, 'Signing failed');
+        }
+    });
+    server.registerTool('propose_change', {
+        description: "Propose new rules for an existing, authorized pass and open the owner's review page, which shows the current rules beside the proposed ones. One owner signature replaces the policies and reissues only the allowances whose cap or term changed; the agent key, its gas and anything the pass holds stay. Give the complete new rule set, not a diff. Nothing changes until the owner signs; poll session_info with wait until status is active again.",
+        inputSchema: {
+            pass: z
+                .string()
+                .optional()
+                .describe('pass id prefix from list_passes; omit if there is one'),
+            ...rulesInput,
+            days: z.number().int().min(1).max(30).describe('agent term from now'),
+            gasCapSui: decimal.describe('lifetime SUI the agent may pull to top up its gas'),
+            gasDailySui: decimal.optional().describe('per UTC day; defaults to a fifth of gasCapSui'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, async ({ pass, ...input }) => {
+        try {
+            const session = await registry.find(pass);
+            const { store } = session;
+            if (!store.state.active)
+                throw new Error('This pass is not authorized yet; propose_authorization is still open');
+            const d0 = store.state.deployment;
+            const { setup, d } = await toSetup(clientFor(d0), d0, {
+                ...input,
+                name: store.state.setup.name,
+                gasSui: display(store.state.setup.gasAmount, 9),
+            });
+            await store.proposeChange(setup);
+            const { origin } = await registry.server(session);
+            const reviewUrl = ownerPageUrl(d, origin, {
+                v: 1,
+                sessionAddress: store.state.sessionAddress,
+                setup,
+                passId: store.state.active.passId,
+            });
+            if (registry.options.openBrowser !== false)
+                openBrowser(reviewUrl);
+            const before = describeSetup(d, store.state.setup), after = describeSetup(d, setup);
+            const changes = after
+                .filter((r) => before.find((b) => b.label === r.label)?.value !== r.value)
+                .concat(before
+                .filter((b) => !after.some((r) => r.label === b.label))
+                .map((b) => ({ label: b.label, value: `removed (was ${b.value})` })));
+            return result({
+                pass: session.id,
+                reviewUrl,
+                rules: renderRows(after),
+                changes: renderRows(changes),
+                next: 'Show the owner the rules text and what changes, send them to the review page, and poll session_info with wait until status is active again. Until then the old rules are in force.',
+            });
+        }
+        catch (error) {
+            return failure(error, 'Cannot propose the change');
+        }
+    });
+    server.registerTool('forget_pass', {
+        description: "Retire a session whose pass is over: refuses while the pass is live, returns the key's unspent gas float to the owner, then deletes the session directory and its key. Works on sessions an earlier version wrote (list_passes shows them as unreadable). Offer this for every pass list_passes reports as closed or stopped, and for proposals the owner never signed.",
+        inputSchema: {
+            pass: z
+                .string()
+                .describe('session id (or prefix) from list_passes, readable or unreadable'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, async ({ pass }) => {
+        try {
+            await registry.all();
+            const ids = [...registry.unreadable.keys(), ...(await registry.all()).map((s) => s.id)];
+            const hits = ids.filter((id) => id.startsWith(pass));
+            if (hits.length !== 1)
+                throw new Error(hits.length ? `${hits.length} sessions match ${pass}` : `No session matches ${pass}`);
+            const { swept } = await registry.forget(hits[0]);
+            return result({
+                forgotten: hits[0],
+                swept,
+                note: swept
+                    ? `Returned ${swept.amount} MIST of gas to the owner (${swept.digest}) and deleted the session.`
+                    : 'Nothing left to return; the session is deleted.',
+            });
+        }
+        catch (error) {
+            return failure(error, 'Cannot forget this session');
+        }
+    });
+    server.registerTool('revoke_pass', {
+        description: "Open a pass's page so the owner can connect their wallet and end it: Stop the agent now (revoke, instant, keeps the pass on chain) or Close the pass (revoke, hand back held objects, delete everything and refund the storage deposit). Nothing happens until the owner signs; this call only opens the page. Confirm afterwards with session_info, which reports status revoked.",
+        inputSchema: {
+            pass: z
+                .string()
+                .optional()
+                .describe('pass id prefix from list_passes; omit to open the owner page listing every pass of the owner, where they can close several in one signature'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ pass }) => {
+        try {
+            if (!pass) {
+                const owners = new Map();
+                for (const s of await registry.all())
+                    if (s.store.state.active)
+                        owners.set(s.store.state.active.owner, s);
+                if (owners.size !== 1)
+                    throw new Error(owners.size
+                        ? 'Passes here belong to several owners; name the pass'
+                        : 'No authorized pass on this machine');
+                const [owner, s] = [...owners.entries()][0];
+                const d = s.store.state.deployment;
+                const { origin } = await registry.server(s);
+                const ownerUrl = `${(d.siteUrl ?? origin).replace(/\/$/, '')}/?network=${d.network}#/owner/${owner}`;
+                if (registry.options.openBrowser !== false)
+                    openBrowser(ownerUrl);
+                return result({
+                    ownerUrl,
+                    next: 'Ask the owner to connect the wallet that created the passes, pick the ones to close and sign once; one transaction closes them all and refunds their storage. To stop one pass without closing it, open that pass by naming it here.',
+                });
+            }
+            const session = await registry.find(pass);
+            if (!session.store.state.active)
+                throw new Error('This pass was never authorized; nothing to revoke');
+            const { passUrl } = await registry.server(session);
+            if (!passUrl)
+                throw new Error('This pass was never authorized; nothing to revoke');
+            if (registry.options.openBrowser !== false)
+                openBrowser(passUrl);
+            const d = session.store.state.deployment, active = session.store.state.active;
+            const status = await readStatus(clientFor(d), d, active, session.store.state.sessionAddress);
+            return result({
+                ...summary(session),
+                alreadyRevoked: status.revoked,
+                passUrl,
+                next: status.revoked
+                    ? 'Already revoked on chain. Close the pass from the same page to get the storage deposit back.'
+                    : 'Ask the owner to connect the wallet that created the pass and pick an ending: Stop the agent now (instant; the pass and its history stay on chain) or Close the pass (also hands back any NAVI position and stakes, deletes the pass and refunds its storage deposit). Their coins never left their address. Then sign.',
+            });
+        }
+        catch (error) {
+            return failure(error, 'Cannot open the owner page');
+        }
+    });
+    return server;
+}
+/** Entry point for `agent-pass mcp`: speaks MCP on stdio until the client disconnects. */
+export async function servePlugin(options) {
+    await mkdir(dirname(options.root), { recursive: true });
+    const registry = new Registry(options);
+    const server = createPluginMcp(registry);
+    const transport = new StdioServerTransport();
+    const stop = () => {
+        void registry.close().then(() => process.exit(0));
+    };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    transport.onclose = stop;
+    await server.connect(transport);
+}
+/**
+ * Entry point for `agent-pass mcp --http`: the same tools on a local HTTP endpoint for agents
+ * that start a fresh process on every wake-up. The registry, and with it each owner page and
+ * its wallet origin, outlives any single agent run.
+ */
+export async function servePluginHttp(options, port) {
+    await mkdir(options.root, { recursive: true, mode: 0o700 });
+    const registry = new Registry(options), bearer = token();
+    const server = createServer(async (request, response) => {
+        try {
+            if (new URL(request.url ?? '/', 'http://localhost').pathname !== '/mcp')
+                return void response.writeHead(404).end();
+            if (request.headers.origin || !authenticated(request, bearer))
+                return void response.writeHead(401).end();
+            const mcp = createPluginMcp(registry), transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                enableJsonResponse: true,
+            });
+            response.on('close', () => {
+                void transport.close();
+                void mcp.close();
+            });
+            await mcp.connect(transport);
+            await transport.handleRequest(request, response, request.method === 'POST' ? await body(request) : undefined);
+        }
+        catch {
+            if (!response.headersSent)
+                response.writeHead(400);
+            response.end();
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', resolve);
+    });
+    const bound = server.address();
+    if (!bound || typeof bound === 'string')
+        throw new Error('No listening address');
+    const endpoint = { url: `http://127.0.0.1:${bound.port}/mcp`, token: bearer };
+    await writeFile(join(options.root, 'mcp-http.json'), JSON.stringify(endpoint, null, 2) + '\n', {
+        mode: 0o600,
+    });
+    const stop = () => {
+        server.close();
+        void registry.close().then(() => process.exit(0));
+    };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    return endpoint;
+}