@ostraagent/mcp 0.1.4 → 0.1.6

package/README.md

@@ -45,12 +45,11 @@ Keep the file and the passphrase off the machine. On a new machine, run `npx -y
 - **Payments:** `pay` (calls a paid HTTP service and pays it from a channel of the vault, refused before signing above `maxPrice`), `open_channel`, `list_channels`, `close_channel`
 - **Ostra AI:** `ostra_ai` (a text, image or video task; Ostra chooses the model by its quality rating within `maxPrice`, paid in USDG from a channel of the vault, and what a task did not cost stays as the vault's credit), `ostra_ai_job` (a video job, saved as a file once completed), `ostra_ai_credit`
 - **Selling services:** `accept_payments`, `seller_balance`, `seller_withdraw`
-- **Privacy:** `shield`, `shield_status`, `auto_shield`, `unshield`, `private_withdraw`
 - **Recovery:** `recovery_status`, `set_guardian`, `set_recovery_policy`, `cancel_recovery`, `support_recovery`, `request_recovery`
 - **Trading:** `tokens`, `token_info`, `pool_info`, `quote_swap`, `buy`, `sell`, `token_vault`, `transfer_token`, `claim_dividends`, `claim_referral`
 - **Launching:** `pairs`, `launch` (paired with USDG, ETH, $OSTRA or a listed Robinhood stock token, at a starting market cap in US dollars, with an optional dev buy and vesting), `launches`, `set_pool_setting`, `set_creator_share`, `release_creator_payout`, `airdrop_fund`, `airdrop_start`, `airdrop_claim`, `airdrop_close`, `vesting_info`, `vesting_release`, `vesting_claim_dividends`
 - **Ostra Swap:** `ostra_swap_quote`, `ostra_swap` (between the agent's vaults of USDG, WETH, $OSTRA, listed stock tokens and launched tokens, routed through Uniswap v3 and v4; tokens by address or symbol)
-- **Private balances:** `private_shield` (from a vault into a private note), `private_balance`, `private_swap`, `private_unshield`, `private_recover` (finds the notes again from the seed alone) (spent with a zero-knowledge proof made on the agent's machine by the WebAssembly prover the package carries)
+- **Privacy:** `private_shield` (from a vault into a private note), `private_balance`, `private_swap`, `private_unshield` (to an address, or with `toPrivateVault` to a new private vault of the agent), `private_withdraw` (from a private vault), `private_recover` (finds the notes and private vaults again from the seed alone), `auto_shield` (everything the creator vault holds beyond what it keeps, into private notes). Notes are spent with a zero-knowledge proof made on the agent's machine by the WebAssembly prover the package carries. A spend does not show which note it spends; the token, the amounts, the times, the vault a shield comes from and an unshield's recipient are public, so a private vault's first balance matches the unshield that paid it
 - **Identity:** `profile`, `upload_image`, `publish_profile`, `set_profile`, `publish_token_metadata`, `set_token_metadata`, `register_agent`, `set_agent_uri`
 
 Every spend is simulated before its one-time key signs it. When a tool refuses, the error says whether it refused before anything was signed.
@@ -68,7 +67,7 @@ All settings are optional.
 | `OSTRA_RPC_URL_FILE` | | A private file (mode 0600) holding the RPC URL, when it carries an API key |
 | `OSTRA_RELAYER_URL` | `https://relayer.ostraagent.xyz` | Sends every transaction, paid in USDG. With `off`, a local fee payer key in `OSTRA_HOME` pays gas in ETH |
 | `OSTRA_KEEPER_URL` | `https://keeper.ostraagent.xyz` | Claims payments for the seller side. `off` disables `accept_payments` |
-| `OSTRA_AGGREGATOR_URL` | `https://aggregator.ostraagent.xyz` | Batches shield deposits. `off` disables `shield` |
+| `OSTRA_AGGREGATOR_URL` | `https://aggregator.ostraagent.xyz` | The shielded pool's batches, for shield deposits kept from before 0.1.6 only. `off` stops them |
 | `OSTRA_AI_URL` | `https://ai.ostraagent.xyz` | Ostra AI, the gateway of the `ostra_ai` tools. `off` disables them |
 | `OSTRA_SWAP_DEPLOYMENT` | Ostra Swap on Robinhood Chain mainnet | Path of another Ostra Swap deployment record (JSON). With `OSTRA_DEPLOYMENT` set and no Ostra Swap record, the Ostra Swap and private tools refuse |
 | `OSTRA_PROVER` | The WebAssembly prover in the package | Path of a native `ostra-prove` binary to prove with instead, or `off` (the private tools then refuse to spend) |

package/dist/ostra-mcp.js

@@ -18,7 +18,7 @@ var __export = (target, all) => {
 var define_OSTRA_PACKAGED_default;
 var init_define_OSTRA_PACKAGED = __esm({
   "<define:OSTRA_PACKAGED>"() {
-    define_OSTRA_PACKAGED_default = { version: "0.1.4", deployment: { version: 1, chainId: 4663, fromBlock: "91991509", token: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168", batchSettlement: "0x4020074e9dF2ce1deE5A9C1b5c3f541D02a10003", vaultImplementation: "0xD20c6744Cfa46d9ec564b119cC923bAb2f9f9331", vaultBeacon: "0xE9F525B9EaeE48d13AEd28fE146F48f2832a18a0", vaultFactory: "0x043a15c514CFE2c797d33520bFF91a5DCdbf2979", poolImplementation: "0xC04d4a222dC1C966640B977608bE29949b0648ec", poolBeacon: "0x30669Ca534921038a531BBE27116d85bB7406fFF", pool: "0x6ea80F2462e5Fd783B0Ec3B2c7BaC96795980CD6", splitFactory: "0xAAf54A483B2c7c2c5ecFc1eDED5ed1619C1bA882", beaconOwner: "0x55533a51d9bd9b06F2D179d919BB31995EF96E5e", launchpad: { hook: "0x63A784afb8905452aDceC471a45E555F5caE68cC", fees: "0x8e79671DC9729476614C78aFcf2345D4c1963801", launchpad: "0xfC57162C0e3f9773F97fEa8d276e957d7c43A6C5", creatorSplit: "0x987994dE6A1d5303B9e3F50977cB0321BA4D033B", dispatcher: "0x44Bb65164b2855f8E80B142d5Fb9bDb72E869986", locker: "0xb593812363bAd70Ee381c7B54c4FC82b0BA3A4A7", devBuy: "0x0e1Fd799E136dcfEcad5695B07Ac5DAc5B2fF4bc", vesting: "0xadD9C1995910457312c156E7D8120D1b447E179a", airdrop: "0xBC798D956aF4c2B104FFC6106d5322294Bc103bb", owner: "0x6569E27A95a6A3E92A311B4Cc6600fed56aA50A2" }, registry: "0xcE6Cc1f93744f4090DA1444Bb8590d9206157506" }, swapDeployment: { chainId: 4663, fromBlock: "94940585", router: "0x5b9686f384A5Fb768B2360cF0B893F0d1E960B01", stake: "0xaDA4FaB9c8aB9165bf4d6cD9d4Da6d6b32Bb4BC6", buyback: "0xd86083031b7Af66ecD5C9c5e90D4C6d8E661F3f5", spendVerifier: "0x0a0E28a81DE6289e5044950163FfE95b37180e3B", privatePool: "0xe4250895Da2499602Cee4e178Fb46A0cF39F5b76" }, prover: { wasm: "0xd5f3069334ab49a2f955e4b4be9493b80c3f7b2a85f4ff2073a327ef5fbc2747", glue: "0x4bc8bef7c755c83daaf833623f85473a20a7c40b390d8d639d9e4353618a0537" }, relayerUrl: "https://relayer.ostraagent.xyz", keeperUrl: "https://keeper.ostraagent.xyz", aggregatorUrl: "https://aggregator.ostraagent.xyz", aiUrl: "https://ai.ostraagent.xyz" };
+    define_OSTRA_PACKAGED_default = { version: "0.1.6", deployment: { version: 1, chainId: 4663, fromBlock: "91991509", token: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168", batchSettlement: "0x4020074e9dF2ce1deE5A9C1b5c3f541D02a10003", vaultImplementation: "0xD20c6744Cfa46d9ec564b119cC923bAb2f9f9331", vaultBeacon: "0xE9F525B9EaeE48d13AEd28fE146F48f2832a18a0", vaultFactory: "0x043a15c514CFE2c797d33520bFF91a5DCdbf2979", poolImplementation: "0xC04d4a222dC1C966640B977608bE29949b0648ec", poolBeacon: "0x30669Ca534921038a531BBE27116d85bB7406fFF", pool: "0x6ea80F2462e5Fd783B0Ec3B2c7BaC96795980CD6", splitFactory: "0xAAf54A483B2c7c2c5ecFc1eDED5ed1619C1bA882", beaconOwner: "0x55533a51d9bd9b06F2D179d919BB31995EF96E5e", launchpad: { hook: "0x63A784afb8905452aDceC471a45E555F5caE68cC", fees: "0x8e79671DC9729476614C78aFcf2345D4c1963801", launchpad: "0xfC57162C0e3f9773F97fEa8d276e957d7c43A6C5", creatorSplit: "0x987994dE6A1d5303B9e3F50977cB0321BA4D033B", dispatcher: "0x44Bb65164b2855f8E80B142d5Fb9bDb72E869986", locker: "0xb593812363bAd70Ee381c7B54c4FC82b0BA3A4A7", devBuy: "0x0e1Fd799E136dcfEcad5695B07Ac5DAc5B2fF4bc", vesting: "0xadD9C1995910457312c156E7D8120D1b447E179a", airdrop: "0xBC798D956aF4c2B104FFC6106d5322294Bc103bb", owner: "0x6569E27A95a6A3E92A311B4Cc6600fed56aA50A2" }, registry: "0xcE6Cc1f93744f4090DA1444Bb8590d9206157506" }, swapDeployment: { chainId: 4663, fromBlock: "94940585", router: "0x5b9686f384A5Fb768B2360cF0B893F0d1E960B01", stake: "0xaDA4FaB9c8aB9165bf4d6cD9d4Da6d6b32Bb4BC6", buyback: "0xd86083031b7Af66ecD5C9c5e90D4C6d8E661F3f5", spendVerifier: "0x0a0E28a81DE6289e5044950163FfE95b37180e3B", privatePool: "0xe4250895Da2499602Cee4e178Fb46A0cF39F5b76" }, prover: { wasm: "0xd5f3069334ab49a2f955e4b4be9493b80c3f7b2a85f4ff2073a327ef5fbc2747", glue: "0x4bc8bef7c755c83daaf833623f85473a20a7c40b390d8d639d9e4353618a0537" }, relayerUrl: "https://relayer.ostraagent.xyz", keeperUrl: "https://keeper.ostraagent.xyz", aggregatorUrl: "https://aggregator.ostraagent.xyz", aiUrl: "https://ai.ostraagent.xyz" };
   }
 });
 
@@ -15997,7 +15997,7 @@ var init_vault = __esm({
         return this.token === this.#config.deployment.token;
       }
       #missing() {
-        if (this.kind === "private") return `private vault ${this.privateIndex} does not exist yet; unshield creates it`;
+        if (this.kind === "private") return `private vault ${this.privateIndex} does not exist yet; it is created on its first use`;
         if (this.kind === "creator") return `this agent has no creator vault${this.#inUsdg() ? "" : ` in ${this.token}`} yet; open it before a launch names it`;
         if (this.kind === "token") return `this agent has no vault in ${this.token} yet; buying the token creates it`;
         return this.kind === "buyer" ? "this agent has no vault yet; call open_vault first" : "this agent has no seller vault yet; call accept_payments first";
@@ -16124,7 +16124,6 @@ var init_vault = __esm({
       }
       open() {
         return this.#serial(async () => {
-          if (this.kind === "private") throw new Error("a private vault is created by unshield, together with the leaf spent into it");
           if (this.kind !== "token" && this.#inUsdg()) await this.#checkToken();
           const vault = await this.vaultAddress();
           const token = this.token;
@@ -16138,7 +16137,7 @@ var init_vault = __esm({
           await this.requireEth(CREATE_VAULT_GAS, "open the vault");
           const txHash = await this.#sender.send([await this.createCall()], this.#options({ prepay: this.kind === "seller" || !this.#paysRelayer() }));
           const result = { vault, token, nonce: "0", created: true, txHash, softLimit };
-          if (this.#sender.relayed && (this.kind === "buyer" || this.kind === "creator") && this.#paysRelayer()) {
+          if (this.#sender.relayed && (this.kind === "buyer" || this.kind === "creator" || this.kind === "private") && this.#paysRelayer()) {
             result.note = "the Ostra relayer paid the vault's creation; the vault owes that price, paid with the first voucher of its channel to the relayer, which this server opens from the vault once it holds tokens (nothing else is relayed for the vault until then)";
           }
           if (!await this.#keys.backupExported()) result.backupReminder = BACKUP_REMINDER;
@@ -21720,11 +21719,11 @@ var init_src2 = __esm({
 });
 
 // ../core/src/private-balance.ts
-import { getAddress as getAddress25, parseAbiItem as parseAbiItem4 } from "viem";
+import { bytesToHex as bytesToHex12, getAddress as getAddress25, parseAbiItem as parseAbiItem4, zeroAddress as zeroAddress12 } from "viem";
 function privateTokens(config) {
   return [config.deployment.token, WETH, ...LAUNCH_PAIRS.filter((p) => p.kind === "ostra" || p.kind === "stock").map((p) => getAddress25(p.address))];
 }
-var PRIVATE_SWAP_DIR, PRIVATE_SHIELD_GAS, PRIVATE_SPEND_DEADLINE_SECONDS, MAX_SLIPPAGE_BPS2, PRIVATE_FEE_GAS, PRIVATE_FEE_MAX_FACTOR, SHIELD_SCAN_GAP, LOGS_CATCH_UP_TRIES, SHIELD_LOG_WAIT_MS, NOTES, TREES, NEXT_RHO, POOL_INDEX, PENDING_PREFIX, shieldedEvent, swappedEvent, unshieldedEvent, address3, PrivateBalanceService;
+var PRIVATE_SWAP_DIR, PRIVATE_SHIELD_GAS, PRIVATE_SPEND_DEADLINE_SECONDS, MAX_SLIPPAGE_BPS2, PRIVATE_FEE_GAS, PRIVATE_FEE_MAX_FACTOR, SHIELD_SCAN_GAP, LOGS_CATCH_UP_TRIES, SHIELD_LOG_WAIT_MS, PRIVATE_VAULT_SCAN_GAP, AUTO_SHIELD_MIN, NOTES, TREES, NEXT_RHO, POOL_INDEX, PENDING_PREFIX, PRIVATE_VAULTS, AUTO_SHIELD, shieldedEvent, swappedEvent, unshieldedEvent, address3, PrivateBalanceService;
 var init_private_balance = __esm({
   "../core/src/private-balance.ts"() {
     "use strict";
@@ -21733,6 +21732,7 @@ var init_private_balance = __esm({
     init_src2();
     init_amount();
     init_chain2();
+    init_config();
     init_relay();
     init_vault();
     PRIVATE_SWAP_DIR = "ostra-swap-private";
@@ -21744,11 +21744,15 @@ var init_private_balance = __esm({
     SHIELD_SCAN_GAP = 20n;
     LOGS_CATCH_UP_TRIES = 30;
     SHIELD_LOG_WAIT_MS = 60 * 60 * 1e3;
+    PRIVATE_VAULT_SCAN_GAP = 200n;
+    AUTO_SHIELD_MIN = parseTokenAmount("1");
     NOTES = "notes.json";
     TREES = "trees.json";
     NEXT_RHO = "next-rho";
     POOL_INDEX = "pool-index.json";
     PENDING_PREFIX = "pending-";
+    PRIVATE_VAULTS = "private-vaults.json";
+    AUTO_SHIELD = "auto-shield-creator.json";
     shieldedEvent = parseAbiItem4("event Shielded(address indexed from, address indexed token, uint256 amount, bytes32 tag, bytes32 commitment)");
     swappedEvent = parseAbiItem4(
       "event PrivateSwapped(bytes32 indexed nullifier, address indexed tokenIn, address indexed tokenOut, uint256 amountIn, uint256 amountOut, uint256 fee, address relayer, bytes32 outTag, bytes32 outCommitment)"
@@ -21834,7 +21838,7 @@ var init_private_balance = __esm({
               shielded.set(tag, [...shielded.get(tag) ?? [], { token: getAddress25(l.args.token), amount: l.args.amount, commitment: l.args.commitment }]);
               notes += 1;
             } else if (l.eventName === "Unshielded") {
-              spends.set(l.args.nullifier.toLowerCase(), { kind: "unshield", v: l.args.amount, fee: l.args.fee });
+              spends.set(l.args.nullifier.toLowerCase(), { kind: "unshield", v: l.args.amount, fee: l.args.fee, recipient: getAddress25(l.args.recipient) });
               notes += 1;
             } else {
               spends.set(l.args.nullifier.toLowerCase(), { kind: "swap", v: l.args.amountIn, fee: l.args.fee, tokenOut: getAddress25(l.args.tokenOut), amountOut: l.args.amountOut, outCommitment: l.args.outCommitment });
@@ -21844,14 +21848,24 @@ var init_private_balance = __esm({
         }
         return { shielded, spends, notes };
       }
-      /** The pool's Shielded, Unshielded and PrivateSwapped logs in [from, to]; a range the RPC refuses as too many logs is split in halves. */
+      /**
+       * The pool's Shielded, Unshielded and PrivateSwapped logs in [from, to], one event per request: Robinhood Chain's
+       * public RPC serves LOG_WINDOW_BLOCKS only for one value per topic position, and a request naming the three events
+       * at once over at most 100,000 blocks (measured 23 Oct 2026, error -32602).
+       */
       async #poolLogs(from, to) {
+        const out = [];
+        for (const event of [shieldedEvent, unshieldedEvent, swappedEvent]) out.push(...await this.#eventLogs(event, from, to));
+        return out;
+      }
+      /** The pool's logs of `event` in [from, to]; a range the RPC refuses as too many logs is split in halves. */
+      async #eventLogs(event, from, to) {
         try {
-          return await this.#p.logsClient.getLogs({ address: this.#pool, events: [shieldedEvent, unshieldedEvent, swappedEvent], fromBlock: from, toBlock: to, strict: true });
+          return await this.#p.logsClient.getLogs({ address: this.#pool, event, fromBlock: from, toBlock: to, strict: true });
         } catch (err) {
           if (from >= to || !/exceeds limit|too many|query returned more than/i.test(String(err.message ?? err))) throw err;
           const mid = from + (to - from) / 2n;
-          return [...await this.#poolLogs(from, mid), ...await this.#poolLogs(mid + 1n, to)];
+          return [...await this.#eventLogs(event, from, mid), ...await this.#eventLogs(event, mid + 1n, to)];
         }
       }
       /** Rebuilds the agent's notes from the seed and the pool's events (see the file comment); the notes kept here become the unspent ones found. */
@@ -21909,6 +21923,7 @@ var init_private_balance = __esm({
         const shields = queue.length;
         const unspent = [];
         const seen = /* @__PURE__ */ new Set();
+        const recipients = /* @__PURE__ */ new Set();
         let followed = 0;
         for (let note = queue.pop(); note !== void 0; note = queue.pop()) {
           if (seen.has(note.commitment.toLowerCase())) continue;
@@ -21920,6 +21935,7 @@ var init_private_balance = __esm({
             unspent.push(note);
             continue;
           }
+          if (spend.kind === "unshield") recipients.add(spend.recipient);
           const change = note.amount - spend.v - spend.fee;
           if (change > 0n) {
             const rho = this.#spendRho("change", note.commitment);
@@ -21944,7 +21960,27 @@ var init_private_balance = __esm({
         const next = counted + 1n > last + 1n ? counted + 1n : last + 1n;
         await this.#p.folder.write(NEXT_RHO, `${next}
 `);
-        return { pool: this.#pool, shields, followed, notes: records.length, tokens: await this.#summary(records) };
+        await this.#recoverPrivateVaults(recipients);
+        return { pool: this.#pool, shields, followed, notes: records.length, tokens: await this.#summary(records), privateVaults: await this.#privateVaultViews() };
+      }
+      /**
+       * The private vaults among `recipients` (the agent's unshields' recipients): numbers 0, 1, ... until
+       * PRIVATE_VAULT_SCAN_GAP numbers in a row past the last one found, and past every number kept here or taken by
+       * unshield.ts, are none of them. Kept with the ones recorded here (a record whose address is not its number's goes).
+       */
+      async #recoverPrivateVaults(recipients) {
+        const kept = (await this.#privateVaults()).filter((r) => this.#privateVaultAddress(BigInt(r.index)) === getAddress25(r.vault));
+        const byIndex = new Map(kept.map((r) => [r.index, r]));
+        const known = [...kept.map((r) => BigInt(r.index)), ...await this.#takenPrivateIndexes()];
+        const floor = known.reduce((m, i) => i + 1n > m ? i + 1n : m, 0n);
+        let last = -1n;
+        for (let i = 0n; recipients.size > 0 && (i <= last + PRIVATE_VAULT_SCAN_GAP || i < floor); i++) {
+          const vault = this.#privateVaultAddress(i);
+          if (!recipients.has(vault)) continue;
+          last = i;
+          if (!byIndex.has(i.toString())) byIndex.set(i.toString(), { index: i.toString(), vault, at: Date.now() });
+        }
+        await this.#savePrivateVaults([...byIndex.values()].sort((a, b) => BigInt(a.index) < BigInt(b.index) ? -1 : 1));
       }
       /** Per token: what `notes` hold, how many, and the largest. */
       async #summary(notes) {
@@ -21986,6 +22022,53 @@ var init_private_balance = __esm({
         await this.#p.folder.write(NOTES, `${JSON.stringify({ version: 1, notes })}
 `);
       }
+      /** The address of private vault `index` (VaultService.vaultAddress of kind "private"; no crank). */
+      #privateVaultAddress(index) {
+        const { chainId, deployment: d } = this.#p.config;
+        const initialKeyRoot = bytesToHex12(this.#p.keys.privateVaultKeychain(chainId, d.token, index).keyRoot(0n));
+        return vaultAddress({ factory: d.vaultFactory, beacon: d.vaultBeacon, token: d.token, initialKeyRoot, initialCrank: zeroAddress12 });
+      }
+      async #privateVaults() {
+        const text2 = await this.#p.folder.read(PRIVATE_VAULTS);
+        return text2 === void 0 ? [] : JSON.parse(text2).vaults;
+      }
+      async #savePrivateVaults(vaults) {
+        await this.#p.folder.ensure();
+        await this.#p.folder.write(PRIVATE_VAULTS, `${JSON.stringify({ version: 1, vaults })}
+`);
+      }
+      async #takenPrivateIndexes() {
+        return this.#p.takenPrivateIndexes === void 0 ? [] : this.#p.takenPrivateIndexes();
+      }
+      /**
+       * A new private vault, kept before it is used: the first number past every one kept here or taken by unshield.ts
+       * whose address has no code and no USDG yet. A number used from another copy of this OSTRA_HOME is passed over and
+       * kept too (it is this seed's private vault), so private_balance and private_withdraw see it.
+       */
+      async #newPrivateVault() {
+        const vaults = await this.#privateVaults();
+        let index = [...vaults.map((r) => BigInt(r.index)), ...await this.#takenPrivateIndexes()].reduce((m, i) => i + 1n > m ? i + 1n : m, 0n);
+        for (; ; index++) {
+          const vault = this.#privateVaultAddress(index);
+          const record = { index: index.toString(), vault, at: Date.now() };
+          vaults.push(record);
+          const used = await this.#p.client.getCode({ address: vault }) !== void 0 || await tokenBalance(this.#p.client, this.#p.config.deployment.token, vault) > 0n;
+          if (used) continue;
+          await this.#savePrivateVaults(vaults);
+          return record;
+        }
+      }
+      /** The private vaults kept here, read now: the ones created or holding USDG (a number whose unshield never landed stays kept, unused). */
+      async #privateVaultViews() {
+        const out = [];
+        for (const r of await this.#privateVaults()) {
+          const vault = getAddress25(r.vault);
+          const exists2 = await this.#p.client.getCode({ address: vault }) !== void 0;
+          const balance = await tokenBalance(this.#p.client, this.#p.config.deployment.token, vault);
+          if (exists2 || balance > 0n) out.push({ index: r.index, vault, exists: exists2, balance: formatTokenAmount(balance) });
+        }
+        return out;
+      }
       async #addNotes(add, remove = []) {
         const drop = new Set(remove.map((c) => c.toLowerCase()));
         const notes = (await this.#notes()).filter((n) => !drop.has(n.commitment.toLowerCase()));
@@ -22024,12 +22107,12 @@ var init_private_balance = __esm({
       async #done(id) {
         await this.#p.folder.remove(`${PENDING_PREFIX}${id}.json`);
       }
-      /** The agent's notes now (operations in flight finished first), and per token what they hold. */
+      /** The agent's notes now (operations in flight finished first), per token what they hold, and its private vaults. */
       balance() {
         return this.#serial(async () => {
           const failures = await this.#refresh();
           await this.#ensureRecovered();
-          return { pool: this.#pool, tokens: await this.#summary(await this.#notes()), inFlight: failures.length };
+          return { pool: this.#pool, tokens: await this.#summary(await this.#notes()), inFlight: failures.length, privateVaults: await this.#privateVaultViews() };
         });
       }
       /** Shields `amount` of `token` from the agent's vault of it into a new note (see the file comment). */
@@ -22037,42 +22120,57 @@ var init_private_balance = __esm({
         return this.#serial(async () => {
           const token = address3(a.token, "token");
           this.#checkToken(token);
-          const prover = this.#prover();
           const decimals = await tokenDecimals(this.#p.client, token);
           const amount = parseUnitsAmount(a.amount, decimals);
           if (amount === 0n) throw new RangeError("amount must be greater than zero");
-          const from = this.#p.vaultFor(token);
-          const s = await from.state();
-          if (!s.exists && from.kind === "buyer") throw new Error("this agent has no vault yet; call open_vault first");
-          if (s.balance < amount) throw new Error(`the vault in ${token} (${s.vault}) holds ${formatUnitsAmount(s.balance, decimals)}, less than ${a.amount}; nothing was signed`);
-          if (!s.exists) await from.open();
-          const sk = this.#sk();
-          await this.#ensureRecovered();
-          let pending = null;
-          const result = await from.operate({
-            gas: PRIVATE_SHIELD_GAS,
-            moves: amount,
-            what: "shield",
-            build: async ({ v, vault, keychain, chainId }) => {
-              const balance = await tokenBalance(this.#p.client, token, vault);
-              if (balance < amount) throw new Error(`the vault holds ${formatUnitsAmount(balance, decimals)} now, less than ${a.amount}; nothing was signed`);
-              const rho = await this.#nextShieldRho();
-              const tag = await tagOf(prover, sk, rho);
-              const escrow = shieldEscrowAddress(this.#pool, token, tag);
-              pending = { kind: "shield", id: tag.slice(2, 18), token, rho, tag, escrow, vaultNonce: v.nonce.toString(), block: (await this.#p.client.getBlockNumber({ cacheTime: 0 })).toString(), at: Date.now() };
-              await this.#keep(pending);
-              const signed = await signVaultTransfer(keychain, v, { chainId, to: escrow, amount });
-              return [spendCall(vault, signed), shieldFromEscrowCall(this.#pool, token, tag)];
-            }
-          });
-          if (result.status !== "sent") return result;
-          const kept = pending;
-          if (kept === null) throw new Error("the shield was sent without its record");
-          const note = await shieldedNote(prover, sk, kept.rho, await this.#p.client.getTransactionReceipt({ hash: result.txHash }), this.#pool);
-          await this.#addNotes([note]);
-          await this.#done(kept.id);
-          return { status: "sent", txHash: result.txHash, token, amount: formatUnitsAmount(note.amount, decimals), note: note.commitment };
+          return this.#shieldFrom(this.#p.vaultFor(token), void 0, token, amount, decimals);
+        });
+      }
+      /** Shields `amount` of `token` from the vault `from` (`source` "creator": the creator vault) into a new note. */
+      async #shieldFrom(from, source, token, amount, decimals) {
+        const prover = this.#prover();
+        const text2 = formatUnitsAmount(amount, decimals);
+        const s = await from.state();
+        if (!s.exists && from.kind === "buyer") throw new Error("this agent has no vault yet; call open_vault first");
+        if (s.balance < amount) throw new Error(`the vault in ${token} (${s.vault}) holds ${formatUnitsAmount(s.balance, decimals)}, less than ${text2}; nothing was signed`);
+        if (!s.exists) await from.open();
+        const sk = this.#sk();
+        await this.#ensureRecovered();
+        let pending = null;
+        const result = await from.operate({
+          gas: PRIVATE_SHIELD_GAS,
+          moves: amount,
+          what: "shield",
+          build: async ({ v, vault, keychain, chainId }) => {
+            const balance = await tokenBalance(this.#p.client, token, vault);
+            if (balance < amount) throw new Error(`the vault holds ${formatUnitsAmount(balance, decimals)} now, less than ${text2}; nothing was signed`);
+            const rho = await this.#nextShieldRho();
+            const tag = await tagOf(prover, sk, rho);
+            const escrow = shieldEscrowAddress(this.#pool, token, tag);
+            pending = {
+              kind: "shield",
+              id: tag.slice(2, 18),
+              token,
+              rho,
+              tag,
+              escrow,
+              ...source === void 0 ? {} : { source },
+              vaultNonce: v.nonce.toString(),
+              block: (await this.#p.client.getBlockNumber({ cacheTime: 0 })).toString(),
+              at: Date.now()
+            };
+            await this.#keep(pending);
+            const signed = await signVaultTransfer(keychain, v, { chainId, to: escrow, amount });
+            return [spendCall(vault, signed), shieldFromEscrowCall(this.#pool, token, tag)];
+          }
         });
+        if (result.status !== "sent") return result;
+        const kept = pending;
+        if (kept === null) throw new Error("the shield was sent without its record");
+        const note = await shieldedNote(prover, sk, kept.rho, await this.#p.client.getTransactionReceipt({ hash: result.txHash }), this.#pool);
+        await this.#addNotes([note]);
+        await this.#done(kept.id);
+        return { status: "sent", txHash: result.txHash, token, amount: formatUnitsAmount(note.amount, decimals), note: note.commitment };
       }
       /** The smallest note of `token` holding at least `need`, or an error naming the largest. */
       async #pick(token, need, decimals, what) {
@@ -22228,11 +22326,19 @@ var init_private_balance = __esm({
           };
         });
       }
-      /** Sends `amount` of `token` out of one private note to `destination` (default: the agent's vault of that token). */
+      /**
+       * Sends `amount` of `token` out of one private note to `destination` (default: the agent's vault of that token), or,
+       * with `toPrivateVault`, to a new private vault of the agent (USDG only; see the file comment).
+       */
       unshield(a) {
         return this.#serial(async () => {
           const token = address3(a.token, "token");
           this.#checkToken(token);
+          if (a.toPrivateVault === true) {
+            if (a.destination !== void 0) throw new RangeError("name a destination or toPrivateVault, not both");
+            if (token !== this.#p.config.deployment.token) throw new RangeError("a private vault holds USDG: unshield another token to an address");
+            if (this.#p.privateVault === void 0) throw new Error("private vaults are not set up here");
+          }
           this.#requireRelayer();
           const prover = this.#prover();
           await this.#refresh();
@@ -22240,10 +22346,11 @@ var init_private_balance = __esm({
           const decimals = await tokenDecimals(this.#p.client, token);
           const v = parseUnitsAmount(a.amount, decimals);
           if (v === 0n) throw new RangeError("amount must be greater than zero");
-          const recipient = a.destination === void 0 ? await this.#p.vaultFor(token).vaultAddress() : address3(a.destination, "destination");
-          if (recipient === "0x0000000000000000000000000000000000000000") throw new RangeError("the destination must not be the zero address");
           const { fee: priced } = await this.#price(token, "unshield");
           const note = await this.#pick(token, v + priced, decimals, `${a.amount} and the relayer's fee`);
+          const privateVault = a.toPrivateVault === true ? await this.#newPrivateVault() : null;
+          const recipient = privateVault !== null ? privateVault.vault : a.destination === void 0 ? await this.#p.vaultFor(token).vaultAddress() : address3(a.destination, "destination");
+          if (recipient === zeroAddress12) throw new RangeError("the destination must not be the zero address");
           const sk = this.#sk();
           const changeRho = this.#spendRho("change", note.commitment);
           const r = await this.#spend(note, (fee) => v + fee, "unshield", async (fee, relayer, deadline, trees) => {
@@ -22254,7 +22361,101 @@ var init_private_balance = __esm({
           const change = changeNote(spend, r.receipt, this.#pool);
           await this.#addNotes(change === null ? [] : [change], [note.commitment]);
           await this.#done(spend.terms.nullifier.slice(2, 18));
-          return { status: "sent", txHash: r.txHash, amountIn: formatUnitsAmount(v, decimals), fee: formatUnitsAmount(r.fee, decimals), recipient, change: formatUnitsAmount(spend.change.amount, decimals) };
+          return {
+            status: "sent",
+            txHash: r.txHash,
+            amountIn: formatUnitsAmount(v, decimals),
+            fee: formatUnitsAmount(r.fee, decimals),
+            recipient,
+            change: formatUnitsAmount(spend.change.amount, decimals),
+            ...privateVault === null ? {} : { privateVault: { index: privateVault.index, vault: privateVault.vault } }
+          };
+        });
+      }
+      /** The private vaults an unshield paid, read now. */
+      privateVaults() {
+        return this.#serial(() => this.#privateVaultViews());
+      }
+      /** The number of the private vault at `vault` kept here (found again from the seed first in a new OSTRA_HOME), or null. */
+      async privateVaultIndex(vault) {
+        const found = (await this.#serial(async () => {
+          await this.#ensureRecovered();
+          return this.#privateVaults();
+        })).find((r) => r.vault.toLowerCase() === vault.toLowerCase());
+        return found === void 0 ? null : BigInt(found.index);
+      }
+      /** Sends USDG from the private vault at `vault` (one an unshield paid), creating the vault first when it does not exist yet. */
+      async withdrawPrivate(a) {
+        const index = await this.privateVaultIndex(address3(a.vault, "vault"));
+        if (index === null) throw new Error(`${a.vault} is not a private vault an unshield of this agent paid (private_balance lists them)`);
+        if (this.#p.privateVault === void 0) throw new Error("private vaults are not set up here");
+        this.#requireRelayer();
+        const pv = await this.#p.privateVault(index);
+        if (await pv.vaultAddress() !== getAddress25(a.vault)) throw new Error(`private vault ${index} is ${await pv.vaultAddress()}, not ${a.vault}`);
+        const s = await pv.state();
+        const created = !s.exists;
+        if (created && this.#p.config.relayerUrl !== null) {
+          const amount = parseTokenAmount(a.amount);
+          if (s.balance < amount + RELAYER_CHANNEL_DEPOSIT) {
+            throw new Error(`private vault ${index} holds ${formatTokenAmount(s.balance)}; its first withdrawal leaves ${formatTokenAmount(RELAYER_CHANNEL_DEPOSIT)} for its relayer channel, so at most ${formatTokenAmount(s.balance > RELAYER_CHANNEL_DEPOSIT ? s.balance - RELAYER_CHANNEL_DEPOSIT : 0n)} now; nothing was signed`);
+          }
+        }
+        if (created) await pv.open();
+        return { ...await pv.withdraw(a.destination, a.amount), ...created ? { created } : {} };
+      }
+      /** Auto-shield of the creator vault (off unless set). */
+      autoShield() {
+        return this.#serial(() => this.#autoShieldSetting());
+      }
+      #creator() {
+        if (this.#p.creator === void 0) throw new Error("the creator vault is not set up here");
+        return this.#p.creator;
+      }
+      async #autoShieldSetting() {
+        const vault = await this.#creator().vaultAddress();
+        const text2 = await this.#p.folder.read(AUTO_SHIELD);
+        if (text2 === void 0) return { vault, enabled: false, keep: formatTokenAmount(RELAYER_CHANNEL_DEPOSIT) };
+        const r = JSON.parse(text2);
+        if (typeof r.enabled !== "boolean" || typeof r.keep !== "string") throw new Error(`${AUTO_SHIELD} is not an auto-shield setting`);
+        return { vault, enabled: r.enabled, keep: formatTokenAmount(parseTokenAmount(r.keep)) };
+      }
+      /** Turns auto-shield of the creator vault on or off; `keep` (USDG, default RELAYER_CHANNEL_DEPOSIT) stays in the vault. */
+      setAutoShield(enabled, keep) {
+        return this.#serial(async () => {
+          this.#creator();
+          if (enabled) this.#prover();
+          const kept = keep === void 0 ? RELAYER_CHANNEL_DEPOSIT : parseTokenAmount(keep);
+          await this.#p.folder.ensure();
+          await this.#p.folder.write(AUTO_SHIELD, `${JSON.stringify({ enabled, keep: formatTokenAmount(kept) })}
+`);
+          return this.#autoShieldSetting();
+        });
+      }
+      /**
+       * One auto-shield step (the sweep): what the creator vault holds beyond `keep`, once at least AUTO_SHIELD_MIN, into
+       * a note. Null when it is off, the creator vault does not exist yet (a launch creates it), it is below that, or a
+       * shield from the creator vault is in flight that the vault no longer holds signed (refresh finishes it); one the
+       * vault holds signed and not landed is sent again first (VaultService.operate), so a lost send does not stop it.
+       */
+      autoShieldStep() {
+        return this.#serial(async () => {
+          if (this.#p.creator === void 0 || this.#p.prover === null) return null;
+          const setting = await this.#autoShieldSetting();
+          if (!setting.enabled) return null;
+          let inFlight = false;
+          for (const name of await this.#p.folder.list()) {
+            if (!name.startsWith(PENDING_PREFIX)) continue;
+            const text2 = await this.#p.folder.read(name);
+            const p = text2 === void 0 ? null : JSON.parse(text2);
+            if (p !== null && p.kind === "shield" && p.source === "creator") inFlight = true;
+          }
+          const token = this.#p.config.deployment.token;
+          const s = await this.#creator().state();
+          if (!s.exists) return null;
+          if (inFlight && s.pendingAction === null) return null;
+          const amount = s.balance - parseTokenAmount(setting.keep);
+          if (amount < AUTO_SHIELD_MIN) return null;
+          return this.#shieldFrom(this.#creator(), "creator", token, amount, await tokenDecimals(this.#p.client, token));
         });
       }
       /** refresh() for the sweep: one at a time with the operations. Returns what is still in flight or failed. */
@@ -22293,7 +22494,7 @@ var init_private_balance = __esm({
           await this.#addNotes([await shieldedNote(prover, sk, p.rho, await this.#p.client.getTransactionReceipt({ hash: l.transactionHash }), this.#pool)]);
           found = true;
         }
-        const s = await this.#p.vaultFor(p.token).state();
+        const s = await (p.source === "creator" ? this.#creator() : this.#p.vaultFor(p.token)).state();
         if (s.nonce === null || s.nonce <= BigInt(p.vaultNonce)) return false;
         if (await tokenBalance(this.#p.client, p.token, p.escrow) > 0n) {
           try {
@@ -22346,7 +22547,7 @@ var init_seed_backup = __esm({
 });
 
 // ../core/src/sessions.ts
-import { bytesToHex as bytesToHex12, getAddress as getAddress26, isAddress as isAddress12 } from "viem";
+import { bytesToHex as bytesToHex13, getAddress as getAddress26, isAddress as isAddress12 } from "viem";
 import { privateKeyToAccount as privateKeyToAccount3 } from "viem/accounts";
 var init_sessions = __esm({
   "../core/src/sessions.ts"() {
@@ -22358,7 +22559,7 @@ var init_sessions = __esm({
 });
 
 // ../core/src/shield.ts
-import { bytesToHex as bytesToHex13, encodeFunctionData as encodeFunctionData13, getAddress as getAddress27, hexToBytes as hexToBytes8, parseSignature } from "viem";
+import { bytesToHex as bytesToHex14, encodeFunctionData as encodeFunctionData13, getAddress as getAddress27, hexToBytes as hexToBytes8, parseSignature } from "viem";
 function leafKeyIndex(attempt, j) {
   if (!Number.isInteger(attempt) || attempt < 0 || attempt >= MAX_LEAF_ATTEMPTS) throw new RangeError(`leaf set ${String(attempt)} is out of range`);
   if (!Number.isInteger(j) || j < 0 || j >= LEAF_KEYS_PER_ATTEMPT) throw new RangeError(`leaf ${String(j)} is out of range`);
@@ -22369,12 +22570,12 @@ function recordName(chainId, token, index) {
 }
 function decodeApproveMessage(message) {
   if (message.length !== APPROVE_MESSAGE_LEN) throw new Error("not an approval message");
-  const chainId = Number(BigInt(bytesToHex13(message.subarray(20, 52))));
-  const pool = getAddress27(bytesToHex13(message.subarray(52, 72)));
-  const key = bytesToHex13(message.subarray(72, 104));
-  const batchId = BigInt(bytesToHex13(message.subarray(104, 112)));
-  const state = bytesToHex13(message.subarray(112, 144));
-  const nextKeyRoot = bytesToHex13(message.subarray(144, 176));
+  const chainId = Number(BigInt(bytesToHex14(message.subarray(20, 52))));
+  const pool = getAddress27(bytesToHex14(message.subarray(52, 72)));
+  const key = bytesToHex14(message.subarray(72, 104));
+  const batchId = BigInt(bytesToHex14(message.subarray(104, 112)));
+  const state = bytesToHex14(message.subarray(112, 144));
+  const nextKeyRoot = bytesToHex14(message.subarray(144, 176));
   const again = approvalMessage({ chainId, pool, key, batchId, state, nextKeyRoot });
   if (again.length !== message.length || !again.every((x, i) => x === message[i])) throw new Error("not an approval message");
   return { chainId, pool, key, batchId, state, nextKeyRoot };
@@ -22743,7 +22944,7 @@ var init_shield = __esm({
             depositId: this.#keys.shieldDepositId(this.#config.chainId, this.#token(), index),
             amount,
             refundOwner: await this.#vault.vaultAddress(),
-            approvalKeyRoot: bytesToHex13(this.#approvalKeys(record).keyRoot(0n))
+            approvalKeyRoot: bytesToHex14(this.#approvalKeys(record).keyRoot(0n))
           };
           if (depositKey(deposit.depositor, deposit.depositId) !== record.deposit) throw new Error("the deposit key does not match the record");
           const validAfter = 0n;
@@ -22846,7 +23047,7 @@ var init_shield = __esm({
         for (let attempt = 0; attempt < 2; attempt++) {
           let index = -1n;
           for (let i = 0n; i < 64n; i++) {
-            if (bytesToHex13(keys.keyRoot(i)) === current.approvalKeyRoot.toLowerCase()) {
+            if (bytesToHex14(keys.keyRoot(i)) === current.approvalKeyRoot.toLowerCase()) {
               index = i;
               break;
             }
@@ -23151,7 +23352,7 @@ function view(r) {
     txHash: r.txHash
   };
 }
-var UNSHIELD_DIR, UNSHIELD_DEFAULT_WINDOW_HOURS, UNSHIELD_MAX_WINDOW_HOURS, LEAF_SPEND_GAS, UnshieldService;
+var UNSHIELD_DIR, UNSHIELD_MAX_WINDOW_HOURS, LEAF_SPEND_GAS, UnshieldService;
 var init_unshield = __esm({
   "../core/src/unshield.ts"() {
     "use strict";
@@ -23160,7 +23361,6 @@ var init_unshield = __esm({
     init_amount();
     init_random();
     UNSHIELD_DIR = "unshield";
-    UNSHIELD_DEFAULT_WINDOW_HOURS = 6;
     UNSHIELD_MAX_WINDOW_HOURS = 24;
     LEAF_SPEND_GAS = 300000n;
     UnshieldService = class {
@@ -23344,7 +23544,7 @@ import {
   getAddress as getAddress30,
   maxUint256,
   parseAbi as parseAbi4,
-  zeroAddress as zeroAddress12
+  zeroAddress as zeroAddress13
 } from "viem";
 var MAX_UINT160, MAX_UINT128, universalRouterAbi, permit2Abi, wrappedErrorAbi;
 var init_wallet_swap = __esm({
@@ -23410,7 +23610,7 @@ var init_src3 = __esm({
 import { randomBytes as randomBytes4 } from "node:crypto";
 import { stat as stat2 } from "node:fs/promises";
 import { join as join3 } from "node:path";
-import { bytesToHex as bytesToHex14 } from "viem";
+import { bytesToHex as bytesToHex15 } from "viem";
 import { privateKeyToAccount as privateKeyToAccount4 } from "viem/accounts";
 async function exists(path) {
   try {
@@ -23448,7 +23648,7 @@ async function openKeys(home, escrow) {
   await ensurePrivateDir(join3(home, WOTS_DIR));
   return new Keys({
     master: master.value,
-    feePayer: privateKeyToAccount4(bytesToHex14(fee.value)),
+    feePayer: privateKeyToAccount4(bytesToHex15(fee.value)),
     store: new FileWotsStore(join3(home, WOTS_DIR)),
     folder,
     masterCreated: master.created,
@@ -23647,9 +23847,9 @@ var init_cli_prover = __esm({
 });
 
 // ../../ostra-swap/sdk/src/wasm-prover.ts
-import { bytesToHex as bytesToHex15 } from "viem";
+import { bytesToHex as bytesToHex16 } from "viem";
 async function sha256Hex(bytes) {
-  return bytesToHex15(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)));
+  return bytesToHex16(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)));
 }
 async function wasmProver(glue, bytes, sha2562) {
   const got = await sha256Hex(bytes);
@@ -23811,7 +24011,10 @@ var init_agent = __esm({
             vaultFor,
             sender: this.sender,
             folder: keys.folder.folder(PRIVATE_SWAP_DIR),
-            localSpends: config.privateLocalSpends
+            localSpends: config.privateLocalSpends,
+            privateVault: async (index) => (await this.privateVault(index)).vault,
+            takenPrivateIndexes: async () => (await this.unshield.list()).map((r) => BigInt(r.index)),
+            creator: this.creator
           });
         }
       }
@@ -23836,8 +24039,29 @@ var init_agent = __esm({
         const creatorKeys = await keys.forCreatorVault(config.chainId, config.deployment.token);
         const agent = new _Agent({ config, client, transport, keys, creatorKeys, escrow, log: log2 });
         await agent.#loadSeller();
+        await agent.#moveAutoShield();
         return agent;
       }
+      /**
+       * An auto-shield of the creator vault set on the shielded pool's leaves (before 0.1.6) is turned on for the private
+       * notes with the same `keep`, then off there; without Ostra Swap or a prover it is left as it is (and logged) for a
+       * start that has them. It never stops the server from starting.
+       */
+      async #moveAutoShield() {
+        try {
+          const old = await this.creatorShield.autoShield();
+          if (!old.enabled) return;
+          if (this.privateBalance === null || this.config.prover === null) {
+            this.#log("auto_shield_not_moved", { vault: old.vault, reason: "private notes need Ostra Swap and a prover" });
+            return;
+          }
+          await this.privateBalance.setAutoShield(true, old.keep);
+          await this.creatorShield.setAutoShield(false);
+          this.#log("auto_shield_moved", { vault: old.vault, keep: old.keep });
+        } catch (err) {
+          this.#log("auto_shield_not_moved", { error: err instanceof Error ? err.message : String(err) });
+        }
+      }
       /** Private vault `index` (unshield made it), with its own records and relayer client. */
       async privateVault(index) {
         const known = this.#privates.get(index);
@@ -23948,7 +24172,10 @@ var init_agent = __esm({
           }
           await step2("unshield", () => this.unshield.sweep());
           if (this.swap !== null) await step2("ostra swap orders", () => this.swap.finishPending());
-          if (this.privateBalance !== null && this.config.prover !== null) await step2("private notes", () => this.privateBalance.refresh());
+          if (this.privateBalance !== null && this.config.prover !== null) {
+            await step2("private notes", () => this.privateBalance.refresh());
+            await step2("private auto-shield", () => this.privateBalance.autoShieldStep());
+          }
         } finally {
           this.#sweeping = false;
         }
@@ -24178,19 +24405,6 @@ function registerTools(server, agent) {
     if (!await agent.sellerReady()) throw new Error("this agent has no seller vault yet; call accept_payments first");
     return agent.seller.withdraw(a.destination ?? await agent.buyer.vaultAddress(), a.amount);
   });
-  tool("shield", "Deposits `leaves` standard leaves from the vault into the shielded pool (through the Ostra aggregator's batches).", { leaves: z.number().int().min(1).max(64) }, (a) => agent.shield.shield(a.leaves));
-  tool(
-    "unshield",
-    `Spends \`leaves\` shielded leaves, each into a new private vault at a random time within windowHours (default ${UNSHIELD_DEFAULT_WINDOW_HOURS}, at most ${UNSHIELD_MAX_WINDOW_HOURS}; 0: now, which lets the spends be timed together).`,
-    { leaves: z.number().int().min(1).max(64), windowHours: z.number().min(0).max(UNSHIELD_MAX_WINDOW_HOURS).default(UNSHIELD_DEFAULT_WINDOW_HOURS) },
-    (a) => agent.unshield.unshield(a.leaves, a.windowHours)
-  );
-  tool("shield_status", "Shield deposits, scheduled unshields and the private vaults.", {}, async () => ({ deposits: await agent.shield.list(), unshields: await agent.unshield.list(), privateVaults: await agent.unshield.vaults() }));
-  tool("auto_shield", "Turns the creator vault's auto-shield on or off (it shields what the vault holds beyond `keep` USDG).", { enabled: z.boolean(), keep: usdg.optional() }, (a) => agent.creatorShield.setAutoShield(a.enabled, a.keep));
-  tool("private_withdraw", "Sends USDG from one of the agent's private vaults.", { vault: address5, destination: address5, amount: usdg }, async (a) => {
-    const ctx = await agent.privateVault(await agent.unshield.indexOf(a.vault));
-    return ctx.vault.withdraw(a.destination, a.amount);
-  });
   tool(
     "ostra_swap_quote",
     "Quotes a swap on Ostra Swap from the agent's vault of tokenIn to its vault of tokenOut (USDG, WETH, OSTRA, listed stock tokens, tokens the Ostra launchpad launched), routed through Uniswap v3 and v4 against USDG or WETH: expected and minimum output, the hub and Ostra's fee (lower with OSTRA locked for the receiving vault). Nothing is signed.",
@@ -24211,11 +24425,11 @@ function registerTools(server, agent) {
   );
   tool(
     "private_recover",
-    "Finds the agent's private notes again from its seed and the pool's events alone (its shields, then each spend's change and swap output), and keeps the unspent ones: for a seed restored on another machine, or notes kept here that look wrong. It runs by itself on first use in a new OSTRA_HOME.",
+    "Finds the agent's private notes again from its seed and the pool's events alone (its shields, then each spend's change and swap output), and keeps the unspent ones, with the private vaults its unshields paid: for a seed restored on another machine, or notes kept here that look wrong. It runs by itself on first use in a new OSTRA_HOME.",
     {},
     () => notes().recover()
   );
-  tool("private_balance", "The agent's private notes in OstraPrivatePool: per token the total, the number of notes and the largest one (a spend uses one note).", {}, () => notes().balance());
+  tool("private_balance", "The agent's private notes in OstraPrivatePool: per token the total, the number of notes and the largest one (a spend uses one note); and its private vaults with what they hold.", {}, () => notes().balance());
   tool(
     "private_swap",
     "Swaps `amount` of tokenIn held in a private note into a new private note of tokenOut, through Ostra Swap, with a zero-knowledge proof made on this machine. The Ostra relayer sends it and is paid from the note (a fee in tokenIn); the change stays private.",
@@ -24224,9 +24438,29 @@ function registerTools(server, agent) {
   );
   tool(
     "private_unshield",
-    "Pays `amount` of a token out of a private note to an address, with a zero-knowledge proof made on this machine. The Ostra relayer sends it and is paid from the note; the change stays private. The default destination is the agent's vault of that token, which an observer can link to the vault that shielded: pay a fresh address for privacy.",
-    { token: swapToken, amount: units, destination: address5.optional() },
-    (a) => notes().unshield({ token: tokenAddress(a.token), amount: a.amount, ...opt("destination", a.destination) })
+    "Pays `amount` of a token out of a private note to an address, with a zero-knowledge proof made on this machine. The Ostra relayer sends it and is paid from the note; the change stays private. The default destination is the agent's vault of that token, which an observer can link to the vault that shielded. With toPrivateVault (USDG only), it pays a new private vault of the agent instead, its own post-quantum vault found again from the seed (private_recover), which private_withdraw spends from. The amount is public, so a round amount, or a note split over several unshields, is harder to match to its shield.",
+    { token: swapToken, amount: units, destination: address5.optional(), toPrivateVault: z.boolean().optional() },
+    (a) => notes().unshield({ token: tokenAddress(a.token), amount: a.amount, ...opt("destination", a.destination), ...opt("toPrivateVault", a.toPrivateVault) })
+  );
+  tool(
+    "private_withdraw",
+    "Sends USDG from one of the agent's private vaults (private_balance lists them) to an address; a private vault an unshield paid is created on this first use.",
+    { vault: address5, destination: address5, amount: usdg },
+    async (a) => {
+      const old = (await agent.unshield.vaults()).find((v) => v.vault.toLowerCase() === a.vault.toLowerCase());
+      if (old !== void 0) return (await agent.privateVault(old.index)).vault.withdraw(a.destination, a.amount);
+      if (agent.privateBalance !== null && await agent.privateBalance.privateVaultIndex(a.vault) !== null) return agent.privateBalance.withdrawPrivate(a);
+      throw new Error(`${a.vault} is not a private vault of this agent (private_balance lists them)`);
+    }
+  );
+  tool(
+    "auto_shield",
+    "Turns the creator vault's auto-shield on or off: every minute, everything the creator vault holds beyond `keep` USDG (default 1, which pays the relayer for its own transactions), once that is at least 1 USDG, is shielded into a private note (private_balance): launch payouts, and USDG put there for a launch too, so turn it off before funding a launch. The shield shows the creator vault it came from.",
+    { enabled: z.boolean(), keep: usdg.optional() },
+    async (a) => {
+      await agent.creatorShield.setAutoShield(false);
+      return notes().setAutoShield(a.enabled, a.keep);
+    }
   );
   tool("recovery_status", "The vault's guardians, recovery policy and any recovery waiting.", {}, () => agent.buyer.recovery());
   tool("set_guardian", "Adds or removes a guardian of the vault (another Ostra vault keeps the recovery post-quantum).", { guardian: address5, enabled: z.boolean() }, (a) => agent.buyer.setGuardian(a.guardian, a.enabled));
@@ -24254,7 +24488,7 @@ function registerTools(server, agent) {
     (a) => lp().sell({ token: a.token, amount: a.amount, ...a.slippageBps === void 0 ? {} : { slippageBps: a.slippageBps }, ...a.referrer === void 0 ? {} : { referrer: a.referrer } })
   );
   tool("token_vault", "The agent's vault for a launched token: address, balance, dividends to claim.", { token: address5 }, (a) => lp().tokenVaultInfo(a.token));
-  tool("transfer_token", "Sends a launched token from the agent's token vault to an address.", { token: address5, destination: address5, amount: units }, (a) => lp().transferToken(a));
+  tool("transfer_token", "Sends a token other than USDG (a launched token, WETH, OSTRA or a stock token) from the agent's vault of it to an address; USDG goes with withdraw.", { token: address5, destination: address5, amount: units }, (a) => lp().transferToken(a));
   tool("claim_dividends", "Claims the dividends the agent's token vault earned, into the agent's vault of the dividend token.", { token: address5 }, (a) => lp().claimDividends(a.token));
   tool(
     "claim_referral",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ostraagent/mcp",
-  "version": "0.1.4",
-  "description": "Ostra Agent's MCP server: an AI agent's own post-quantum USDG vault on Robinhood Chain, with payments, a shielded pool and the Ostra launchpad. The agent needs no ETH.",
+  "version": "0.1.6",
+  "description": "Ostra Agent's MCP server: an AI agent's own post-quantum USDG vault on Robinhood Chain, with payments, private balances and the Ostra launchpad. The agent needs no ETH.",
   "keywords": [
     "mcp",
     "model-context-protocol",