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

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,424 @@
-# Temporary Holding Version
+# Sui Agent Pass
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Your money. Your rules. AI at work.**
+
+Sui Agent Pass lets an AI agent run your onchain finance under a policy you write once. The agent
+pays, trades, lends and stakes; Sui checks every transaction against the policy at settlement.
+A policy is more than a spending limit: it names who the agent can pay, which markets it can
+trade on and at what price, how much lending risk it can take, which validators it can stake
+with, and how long its access lasts. Each new protocol plugs in as a new policy module.
+
+An owner authorizes a new agent key with Slush. The agent builds its own programmable
+transactions, a local MCP signer holds the agent key on the owner's machine and signs complete
+transaction bytes, and the chain decides what executes. No hosted service ever holds a key.
+
+One pass per agent, and the agent never owns anything:
+
+- **Your coins stay in your own address.** Setup issues two allowances (`sui::allowance`) bound
+  to the pass, one per coin. Every agent action draws from your address balance through an
+  allowance, is checked by the pass's policies, and returns its proceeds to your address. The
+  pass never holds a coin.
+- **The pass holds the rules and the objects the agent operates.** A NAVI lending position is
+  an object that can only be used under its owner's signature, so it sits in the pass where the
+  agent can run it. Only you can take it out, and taking it out hands you the position directly.
+- **A receipt in your wallet points at each pass**, so from any device you can find your passes,
+  read their positions, and reclaim them. Authority stays with your address, never the receipt.
+
+The pass is an account, not a typed container: each action names its coin. The owner installs
+one policy per kind of action and coin. Transfers go to recipients the owner named; the agent
+never supplies an address. Swaps run on the DeepBook and Cetus pools the owner listed, within
+per-trade and daily caps and above a price floor. Lending supplies collateral to NAVI and, if
+enabled, borrows against it while keeping the health factor above the owner's floor. Staking
+puts SUI with the validators the owner listed (or any active one), within per-stake and daily
+caps; the stake object stays in the pass and unstaking returns the SUI to the owner. An action
+with no policy for its coin is refused. Revocation ends the agent's term and deletes the
+allowances. The package references `sui::allowance`, so it needs protocol 137 or later, which
+testnet, devnet and mainnet all run. The demo stays on localnet, testnet and devnet; mainnet
+serves compatibility tests with small sums until launch.
+
+The agent pays its own gas from the session address. Setup seeds an initial gas stipend and issues
+a separate small SUI allowance for gas; when the session's balance runs low the agent tops it up
+from that allowance, within its own lifetime cap and daily window, so gas spend is bounded apart
+from the asset rules. Owners cannot bill an agent's transaction gas to the wallet directly yet,
+because gas is authorized by a signature and `sui::allowance` cannot authorize it.
+
+Transfers and staking are the real thing on every network. DeepBook, Cetus and NAVI are called
+through their mainnet interfaces; off mainnet the demo publishes local stand-ins with the same
+signatures over small mock markets, and the Move manifest lists the real packages as mainnet
+replacements. See `move/protocols/README.md`.
+
+This repository is fully self-contained. There is no broker, authorization database,
+intent adapter, or transaction builder inside MCP.
+
+## Install (planned distribution)
+
+Not published yet. Once the package is on npm and the immutable contracts are published on chain,
+a user needs no clone, no build, and no toolchain. The client ships the per-network deployment IDs
+(`deployments/<network>.json`) and resolves them with `--network`:
+
+```sh
+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
+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
+starts the signer when it needs it. In production the page is our site at a fixed origin, so the
+agent cannot change what you see or sign; in development the same build is served from the local
+port (see "The site" in `docs/ARCHITECTURE.md`). There is no setup wizard: the agent composes
+the rules from your words and the facts the server gives it (coins, pools, balances, quotes), and
+the review page is where you check them. For a private publish:
+
+```sh
+agent-pass connect                          # asks which agents; or --client <name>
+```
+
+Publishing the Move package and installing the Sui toolchain are maintainer steps, never on a
+user's machine. See the release checklist below.
+
+## Use it with your agent
+
+The signer speaks MCP, so any agent that can load an MCP server can use it. The protocol is
+the same for every client; where each one keeps its server list is not, so `connect --client`
+writes or prints the entry in the right place:
+
+| `--client`       | What it does                                                           |
+| ---------------- | ---------------------------------------------------------------------- |
+| `claude-code`    | `claude mcp add` in user scope                                         |
+| `claude-desktop` | Writes into `claude_desktop_config.json`                               |
+| `cursor`         | Writes into `~/.cursor/mcp.json`                                       |
+| `hermes`         | Prints the `mcp_servers` block for `~/.hermes/config.yaml`             |
+| `codex`          | Prints the `[mcp_servers.agent-pass]` block for `~/.codex/config.toml` |
+| `json`           | Prints a generic `mcpServers` entry                                    |
+
+The entry is `agent-pass mcp`, a stdio server the client starts when it needs it and stops with
+it. It covers every pass on this machine, exposes `session_info` and `sign_transaction`, and
+adds the owner tools (`list_passes`, `propose_authorization`, `revoke_pass`), so the agent can
+also set a pass up. While it runs it also serves each pass's HTTP signer, which the SDK uses.
+`connect --session <directory>` instead points a client at one session's foreground signer
+(`agent-pass serve`), for agents that cannot start a process themselves.
+
+Acting is a Node script against the SDK. `session_info.sdk.install` is the install command
+(`npm install <this checkout>` after `npm run build` while the package is unpublished), then:
+
+```ts
+import { Agent, pickValidator, send, stake, swap } from '@mysten-incubation/sui-agent-pass/agent';
+import { SUI, units } from '@mysten-incubation/sui-agent-pass/domain';
+
+const agent = await Agent.open(directory); // from session_info
+const usdc = agent.identity.deployment.coins.find((c) => c.symbol === 'USDC')!;
+const out = await agent.submit(
+	swap(agent.identity, { coinIn: SUI, coinOut: usdc.type }, units('0.01', 9), units('0.019', 6)),
+);
+// out.success, out.reason (the owner's rule on a refusal), out.balanceChanges
+```
+
+`submit` signs through the session signer, submits to Sui and returns the persisted outcome; it
+throws when nothing executed, so a dry-run refusal is never mistaken for enforcement.
+[docs/AGENT.md](docs/AGENT.md) documents the SDK and the contract for hand-built PTBs. Agents
+that do not speak MCP get the same two operations as plain HTTP with the bearer from
+`mcp.token`: `GET /v1/session` and `POST /v1/sign` with `{ "transactionBytes": "<base64>" }`.
+
+## Run the rehearsal
+
+Clone the repository with your authorized GitHub account:
+
+```sh
+gh repo clone MystenLabs/sui-agent-pass ~/github/sui-agent-pass
+```
+
+Requires Node 22+, npm, and Sui 1.81.1 (`mainnet-v1.81.1`, the release mainnet runs; `npm run
+toolchain` installs it with `mvr`). The project checks `SUI_BIN`, then
+`~/.cache/sui-agent-pass/toolchain/sui`, then `sui` on PATH. Older installations are not used if
+the project toolchain is present. The single Move package references `sui::allowance`, so it
+builds and publishes only with a chain that has it enabled: localnet from this toolchain,
+testnet, devnet, or mainnet (protocol 138).
+
+```sh
+cd ~/github/sui-agent-vault
+npm ci
+npm run toolchain
+npm run build
+npm run demo
+```
+
+The command starts its own fresh local Sui network, publishes immutable demo contracts,
+creates separate owner/publisher/session identities, authorizes the session, starts MCP,
+and prints an owner dashboard URL and Claude connection command. It keeps the chain and
+signer alive until `quit` or Ctrl-C. Keys stay in ignored private directories.
+
+Commands in the rehearsal: `status`, `send` (5 USDC to the recipient named `owner`), `swap`
+(0.01 SUI on DeepBook), `cetus` (0.01 SUI on Cetus), `supply` (0.2 SUI to NAVI), `borrow`
+(0.15 USDC from NAVI), `stake` (1 SUI with the localnet validator), `unstake` (the held
+stake, back to the owner), `over` (11 USDC against a 10 per-transfer limit), `revoke`, `quit`.
+`npm run demo -- --smoke` runs the sequence automatically and exits. After revocation the
+allowance objects no longer exist, so a transaction that names one is refused before execution
+rather than recorded as a chain failure.
+
+**The default rehearsal uses a generated test owner, not Slush.** It proves chain execution
+and MCP signing. For the wallet connection/signature flow use the flow below.
+
+## Slush + Claude Code
+
+Use a deployed configuration, or `npm run devnet -- --owner <address>`, which publishes to
+devnet with a faucet-funded publisher, funds your wallet address from the faucet and writes the
+deployment to `~/.sui-agent-pass/deployment.json` for the Claude Code plugin. Slush offers
+mainnet, testnet and devnet only. `npm run demo -- --wallet` keeps a localnet alive and prints a
+funded throwaway owner key for a wallet that accepts a custom RPC URL; not verified with any.
+
+```sh
+# Prepare valueless testnet contracts using a separate deployment identity (testnet is the
+# default network):
+npm run deploy -- create --directory .local/testnet
+# If the faucet cannot provide enough funds, the command prints the deployment address.
+# Fund it with at least 11 test SUI, then:
+npm run deploy -- resume --directory .local/testnet
+
+# A private deployment.json replaces the bundled network for new passes:
+node dist/cli.js connect   # then ask the agent; it passes deployment: .local/testnet/deployment.json
+# devnet works the same way:
+npm run deploy -- create --network devnet --directory .local/devnet
+```
+
+The agent asks what the pass is for and proposes the rules: recipients with per-transfer and
+daily caps for each coin; for each trade direction the pools, per-trade and daily caps and a
+price floor; for each lent coin per-action and daily caps, whether borrowing is allowed and a
+health-factor floor; the validators it may stake with and per-stake and daily caps (a stake is
+at least 1 SUI, the system's minimum); a lifetime cap per coin and the gas terms. It quotes the
+exact rules text the page will show, generates a key and opens the review page. Connect Slush;
+allowances draw only from your address balance, never from coin objects, so the page reads what
+you hold on both sides and shows how much of your coins the signature converts into that balance
+to cover the caps, with a faucet link if your wallet is short. Gas for your own signature comes
+from either side. Sign. One PTB creates the pass and hands you its receipt, converts the coins,
+issues the allowances over your own balance, installs the policies, opens the pass's NAVI
+account when lending is allowed, and sends SUI to the session's **address balance** for gas. The
+service re-reads everything that landed on chain and compares it with what you reviewed before
+the signer serves the key.
+
+Register the agents that may use your passes once with `connect` (it asks which ones it finds on
+the machine). Then start Claude anywhere:
+
+```sh
+claude
+```
+
+The registration is `agent-pass mcp` in Claude Code's user scope, a stdio server Claude starts
+when it needs it. It contains no key and no token. If that MCP name already exists, remove the
+old entry with `claude mcp remove agent-pass` before reconnecting.
+
+```sh
+node dist/cli.js status --session /absolute/session/directory
+node dist/cli.js serve --session /absolute/session/directory    # advanced: a foreground HTTP signer
+```
+
+Closing Claude does not revoke the chain session;
+the owner page's **Stop the agent now** button does, and **Close the pass** returns everything.
+Your coins never left your address. If the
+agent opened a NAVI position, **Reclaim NAVI position** on the owner page takes the account cap
+into your wallet: the position is then yours to manage on NAVI directly and the agent has
+nothing to lend on. Each stake the agent opened has a **Reclaim** button of its own, which moves
+that `StakedSui` into your wallet. The pass also provides owner-only policy edits, documented in
+the agent API guide.
+
+## Claude Code plugin
+
+The plugin runs the whole owner flow from inside Claude Code. You describe what the agent may
+do; Claude proposes rules; the plugin renders them, opens the review page, and you sign once in
+Slush. After that Claude acts through the same session, with no `connect` step and no second
+terminal.
+
+```sh
+cd ~/github/sui-agent-vault
+npm ci && npm run toolchain && npm run build
+# Publish with a faucet-funded key, fund your Slush address from the faucet, and write
+# ~/.sui-agent-pass/deployment.json:
+npm run devnet -- --owner <your Slush address>
+cd ~/anywhere && claude --plugin-dir ~/github/sui-agent-vault/plugin
+```
+
+Then, in Claude Code:
+
+> Manage 1 SUI and 100 USDC for me. Sell at most 0.1 SUI a day on DeepBook, never below
+> 1.8 USDC. You may pay alice (0x…) up to 10 USDC a time and 20 a day. One week.
+
+Claude calls `propose_authorization`, prints the rules text the tool returned, and the review
+page opens. Connect Slush, check that the page shows the same rules, sign. Claude waits on
+`session_info` until the pass is confirmed and its policies match, then works within the rules
+with scripts against the SDK (`@mysten-incubation/sui-agent-pass/agent`), or with its own PTBs and
+`sign_transaction`. `/agent-pass:pass-status` shows balances and today's
+usage; `/agent-pass:pass-revoke` reopens the owner page for the revocation signature. The
+guidance Claude follows is [`docs/PLAYBOOK.md`](docs/PLAYBOOK.md), which the MCP serves to every
+client as the `agent-pass://playbook` resource; the plugin skills only point at it.
+
+The MCP is `node dist/cli.js mcp`. It keeps sessions under `~/.sui-agent-pass/sessions/` and
+reads `deployment.json` from that directory; Claude can also pass another deployment path to
+`propose_authorization`. The plugin and Claude Code run as the same OS user: the session key
+is not hidden from Claude by the operating system, and the on-chain rules are the boundary.
+
+## The site
+
+`npm run build` produces `web-dist/`, one static site that reads the chain directly and needs
+no signer or session. `#/authorize/<proposal>` is the review page `setup` and the plugin open:
+the rules come from the URL, the page builds the authorization against the package IDs it was
+built with, your wallet signs, and the local signer finds the result on chain. Paste a pass id
+or an owner address, or connect a wallet, and see the pass's rules, the owner's balances and
+allowances, what the pass holds, and every transaction the agent sent with the chain's verdict
+and the rule behind each refusal. Owner actions (revoke, reclaim a position or a stake, close
+the pass) are wallet signatures from the same page. Closing deletes the pass, its policies, its
+receipt and any remaining allowances in one transaction and hands back anything it still holds;
+the storage deposits of everything deleted return with that transaction's gas. `#/booth` is the event view: the latest passes on the
+package and a live feed of every call into it, refreshing every four seconds.
+
+The pages use the Sui brand fonts, which are licensed and not in git: put the brand kit under
+`.local/brand/` and run `npm run brand` before building, or the pages fall back to system fonts.
+The build bundles `deployments/<network>.json`; `?network=testnet` picks one, otherwise the
+first of testnet, devnet, localnet, mainnet that exists. To host it, serve `web-dist/` as static
+files at a fixed origin and set `siteUrl` in the deployment file. To run it locally against any
+deployment:
+
+```sh
+npm run explorer -- --deployment .local/devnet/deployment.json
+```
+
+## Basecamp film and slides
+
+Every word of the film (voiceover and on-screen text) and of the two slides lives in
+[`presentation/copy.md`](presentation/copy.md). Edit it, then run `npm run slides` (seconds) or
+`npm run demo:film` (about six minutes, since the voice paces the recording).
+
+`npm run demo:film` records the three-minute cut on a fresh localnet and writes
+`scripts/film/out/basecamp-silent.mp4` (picture only, for the presenter's voiceover),
+`basecamp-scratch-vo.mp4` (the same cut read by a scratch voice, for pacing) and
+`basecamp-script.md` (the voiceover with a timecode per line). The voice paces the recording, and quiet waits on the agent are cut. On a
+published network: `npm run film:record -- --deployment <deployment.json> --funder <key file>`,
+then `npm run film:edit`. There the owner signs in the real Slush extension, copied from the
+local Chrome profile (or `SLUSH_EXTENSION`) into a throwaway browser profile with a fresh key;
+the stage shows Slush's own screens as a docked panel, and what the key has left goes back to
+the funder afterwards. Localnet keeps the page's dev wallet, since Slush has no localnet.
+`node --import tsx scripts/slides/render.ts` renders the two concept
+slides to `.local/basecamp/`. Both need the brand kit (`npm run brand`) and Codex on the PATH.
+Drafts use the free edge-tts voice. `npm run film:final` (with `ELEVENLABS_API_KEY` set) reads the
+lines in the account's ElevenLabs voice (`ELEVENLABS_VOICE`, default `Tech`); clips are cached
+under `.local/tts-cache/`, so an unchanged line costs no credits on a re-recording.
+
+### Changing the voice or the words
+
+The voice paces the recording, so a new voice or a new line means a new recording. To re-record
+the testnet cut as it was made for Basecamp, with the owner signing in Slush:
+
+1. Have Codex (`codex`) on the PATH and Slush installed in Chrome, then `npm install`, `npm run
+brand` and `npx playwright install chromium`.
+2. Put a funded testnet key (the `suiprivkey…` string, a few SUI; each run uses about 2) in a
+   file, for example `.local/testnet/funder.key`. Get testnet SUI at <https://faucet.sui.io>.
+3. Change the words in `presentation/copy.md` if you want to. `[tone]` tags and `...` shape the
+   ElevenLabs reading; the free draft voice ignores them.
+4. Record with your own ElevenLabs voice:
+
+   ```sh
+   export ELEVENLABS_API_KEY=… ELEVENLABS_VOICE="Your voice name"
+   npm run film:record -- --final --deployment deployments/testnet.json --funder .local/testnet/funder.key
+   npm run film:edit
+   ```
+
+   Leave out `--final` for a free draft first. The cut lands in `scripts/film/out/`:
+   `basecamp-scratch-vo.mp4` is the voiced film and `basecamp-silent.mp4` the same picture with no
+   sound, for recording a human voiceover over it with `basecamp-script.md` as the timecoded script.
+
+## Show it to someone
+
+- [English demo script](docs/DEMO.md): pitch, exact commands, Claude prompts, expected results.
+- [Chinese presenter instructions](docs/DEMO.zh-CN.md): operator notes with English prompts and narration.
+- [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.
+
+## Checks
+
+```sh
+npm run check
+npm test
+npm run test:move
+npm run build
+AGENT_PASS_BROWSER_TEST=1 npm run test:integration
+# Optional live model check, using fresh localnet funds and your Claude login:
+npm run test:claude
+```
+
+Browser verification uses installed Google Chrome and a wallet-standard **test wallet**.
+It runs with a Chinese browser locale to verify the demo still displays English dates and copy.
+It is not evidence of a live Slush extension signature. Integration tests submit signed
+invalid transactions and inspect persisted failures; ordinary SDK simulations are not
+counted as chain refusals. Each test owns and stops its localnet process.
+
+## Release checklist
+
+Publishing is a maintainer step, done once per network and once per npm release. None of it runs
+on a user's machine.
+
+Publish the contracts to a network:
+
+1. `npm run toolchain` and `npm run build`.
+2. `npm run deploy -- create --network testnet --directory .local/testnet`. Testnet is the
+   default. Mainnet needs a manually funded publisher (no faucet): `create --network mainnet`
+   prints the address, `resume` publishes once it holds 2 SUI.
+3. Commit the resulting `deployment.json` here as `deployments/<network>.json`.
+
+Publish the npm client:
+
+1. Confirm `npm run check`, `npm test`, `npm run test:move`, `npm run build`, and
+   `AGENT_PASS_BROWSER_TEST=1 npm run test:integration` pass.
+2. `npm pack --dry-run` to confirm the tarball holds `dist/`, `web-dist/` and `deployments/`.
+3. Finalize the package name and version, remove `"private": true`, then `npm publish`;
+   `prepublishOnly` rebuilds first.
+
+## Scope
+
+Demo only, localnet/testnet/devnet, SUI and a test **USDC** that the demo faucet mints (not
+Circle's USDC). Off mainnet DeepBook, Cetus and NAVI are exercised through local stand-ins that
+keep the mainnet function signatures over constant-product pools and a principal-only lending
+market. The package also builds against the real protocols (`sui move build -e mainnet`) and
+`npm run deploy -- create --network mainnet` publishes it there with Circle's USDC and the real
+pools, for compatibility tests; no mainnet publication is claimed yet. The demo packages are
+made immutable when published; the mainnet package keeps its upgrade cap.
+
+**Policies.** Each rule set is one on-chain policy object for one coin type, installed by the
+owner and metered per UTC calendar day. Transfers reach only named recipients. Swaps run only
+on listed pools, within input caps, above a static price floor and the agent's own `min_out`;
+proceeds return to the owner's address. Lending pins the NAVI pool and asset index, caps each
+action, and refuses a withdraw or borrow that would leave the position below the owner's
+health-factor floor; the floor sits on the collateral policy too, so a withdraw cannot breach
+it. Positions belong to the pass's own NAVI account cap, never to the agent. Owners edit
+policies by removing and reinstalling them, which keeps the meters.
+
+**Allowances.** `sui::allowance` draws from address balances only, so setup moves the chosen
+coins from the owner's coin objects into the owner's own address balance. Anything the owner
+spends from that balance later simply reduces what the agent can withdraw; a spend above the
+live balance is refused at signing. A session's allowances, the two asset allowances and the
+separate SUI gas allowance, share one expiry and are deleted together on revocation. The pass
+accepts only allowances funded by its owner for its agent, and only it can spend them. A
+repayment to NAVI is charged to the allowance in full before NAVI runs, so an over-payment
+returns to the owner but still counts against the allowance; the agent should size repayments
+from the live debt.
+
+**Staking.** Real on every network. The policy lists validators (empty means any active one)
+and caps each stake and the day. The `StakedSui` the agent opens is held by the pass; the
+agent may unstake it, which sends principal and rewards to the owner's address, and the owner
+may reclaim it as an object. The system's own 1 SUI minimum per stake applies.
+
+**Objects.** The pass holds objects under typed keys: a protocol account under its adapter's
+key, a stake under its ID, anything else under its own ID. Only the owner deposits or withdraws
+them. Withdrawing the NAVI account cap moves the position with it, into the owner's wallet,
+where NAVI's own UI shows it; withdrawing a stake makes it an ordinary `StakedSui` there. An
+emptied pass (no policies, no objects) can be destroyed by the owner.
+
+The gas stipend belongs to the session address and is freely spendable. A local service and
+Claude running under the same OS user are not a private-key isolation boundary: the chain rules
+survive key theft, while key confidentiality needs a separate identity or container. The private
+owner/publisher fixture keys never enter the signing service.

package/deployments/README.md

@@ -0,0 +1,28 @@
+<!-- Copyright (c) Mysten Labs, Inc. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
+# Bundled deployments
+
+One `deployment.json` per public network, committed here and shipped in the npm package (see the
+`files` field in `package.json`). Each records the published package and object IDs, the gRPC URL
+and the chain identifier for that network. The stdio server loads one of these when
+the agent names a `network` in `propose_authorization`, so an installed client needs no local
+publish; a private `deployment.json` under `~/.sui-agent-pass` or a `deployment` path overrides.
+
+`mainnet.json` is the mainnet test copy of the package (`0x4c9010b0…f403`, upgraded to
+`0x08d82880…f744`, version 2), published for dogfooding and for testing the publish and upgrade
+process with small sums; the real launch will be a fresh publish and a new file here. Add
+`siteUrl` to it once the hosted site has its address, so the plugin sends owners there.
+`testnet.json` is the current package (Sui Agent Pass), published to testnet on 2026-10-20 with
+the version gate and the per-coin deployment shape (`coins`, `pools`, NAVI `reserves`, the demo
+faucet). Any Move change means a new publish and a new file here. `npm run devnet` publishes to devnet and writes its
+`deployment.json` for the plugin; `npm run deploy -- create --network <name>` publishes to
+testnet or devnet. At launch, commit the resulting `deployment.json` here as `<name>.json`.
+
+The site build (`npm run build`) copies these files into `web-dist/deployments/`, so the hosted
+site serves whichever networks are committed here. A deployment's `siteUrl` is where the
+plugin sends owners to review and sign; without it the local signer serves the same build.
+
+The package references `sui::allowance`, which testnet, devnet and mainnet (protocol 138) all
+have. A mainnet publish needs a manually funded publisher (mainnet has no faucet):
+`npm run deploy -- create --network mainnet`.