@supercuts-walrus/backend 0.1.0 → 0.1.1

package/dist/buyer-setup.js

@@ -69,7 +69,7 @@ function writePolicy(home, config) {
     const base = { ...mandate };
     delete base.allowedCapabilityIds;
     delete base.allowedCapabilityClasses;
-    const next = { ...base, version: "supercuts.mandate.v2", allowedCommands: [...new Set([...mandate.allowedCommands, "deal.execute", "deal.get", "deal.resume", "deal.evidence", "deal.delivery", "deal.catalog", "deal.policy", "settlement.plan", "memory.inventory"])], allowedCounterparties: config.allowedCounterparties ?? [], perDealCeiling: config.perDealCeiling, totalRunBudget: config.totalBudget, expiresAt: config.expiresAt, requiredPrivacy: "any", requireSettlementPlan: true, allowedRails: config.allowPublicX402 === true ? ["shielded", "x402"] : ["shielded"], allowPublicX402: config.allowPublicX402 === true, ...(config.allowedCapabilityIds ? { allowedCapabilityIds: config.allowedCapabilityIds } : {}), ...(config.allowedCapabilityClasses ? { allowedCapabilityClasses: config.allowedCapabilityClasses } : {}) };
+    const next = { ...base, version: "supercuts.mandate.v2", allowedCommands: [...new Set([...mandate.allowedCommands, "deal.execute", "deal.get", "deal.resume", "deal.evidence", "deal.delivery", "deal.catalog", "deal.policy", "settlement.plan", "memory.inventory", "remote.research"])], allowedCounterparties: config.allowedCounterparties ?? [], perDealCeiling: config.perDealCeiling, totalRunBudget: config.totalBudget, expiresAt: config.expiresAt, requiredPrivacy: "any", requireSettlementPlan: true, allowedRails: config.allowPublicX402 === true ? ["shielded", "x402"] : ["shielded"], allowPublicX402: config.allowPublicX402 === true, ...(config.allowedCapabilityIds ? { allowedCapabilityIds: config.allowedCapabilityIds } : {}), ...(config.allowedCapabilityClasses ? { allowedCapabilityClasses: config.allowedCapabilityClasses } : {}) };
     writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
     chmodSync(path, 0o600);
     writeFileSync(join(home, "deal-sellers.json"), `${JSON.stringify(config.directoryUrl ? { directoryUrl: origins([config.directoryUrl])[0], origins: config.sellerOrigins?.length ? origins(config.sellerOrigins) : [] } : origins(config.sellerOrigins ?? []), null, 2)}\n`, { mode: 0o600 });
@@ -206,7 +206,7 @@ export async function approveBuyerSeller(home, capabilityId) {
     profile.policy.allowedCounterparties = updated.allowedCounterparties;
     writeFileSync(path, `${JSON.stringify(updated, null, 2)}\n`, { mode: 0o600 });
     writeFileSync(profilePath, `${JSON.stringify(profile, null, 2)}\n`, { mode: 0o600 });
-    return { capabilityId, sellerId: registration.manifest.sellerId, approved: true };
+    return { capabilityId, sellerId: registration.manifest.sellerId, approved: true, manifestHash: registration.manifest.manifestHash, description: registration.manifest.description, priceBand: registration.manifest.priceBand, asset: registration.manifest.asset, supportedRails: registration.manifest.supportedRails, expiresAt: registration.manifest.expiresAt };
 }
 export async function addBuyerPrivacyRule(home, capabilityId) {
     const app = new Phase3App(home);

package/dist/cli.js

@@ -2,18 +2,21 @@
 import { Phase3App, errorOutput, homePath, initialize, parseArgs } from "./phase3.js";
 import { addBuyerPrivacyRule, approveBuyerSeller, createBuyerSession, promptBuyerSetup, renewBuyer, setupBuyer } from "./buyer-setup.js";
 import { onboardingDoctor } from "./onboarding-doctor.js";
+import { executeFunding, prepareFunding } from "./funding.js";
+import { packageHostedSeller } from "./seller-package.js";
 const words = process.argv.slice(2);
 let command = words.shift() ?? "";
-if (["wallet", "offer", "pay", "resource", "memory", "audit", "capability", "settlement", "setup", "policy", "onboarding"].includes(command))
+if (["wallet", "offer", "pay", "resource", "memory", "audit", "capability", "settlement", "setup", "policy", "onboarding", "onboard", "funding", "seller"].includes(command))
     command += `.${words.shift() ?? ""}`;
 try {
     if (!command || command === "help" || command === "--help" || command === "setup.") {
-        process.stdout.write(`${JSON.stringify({ schemaVersion: "supercuts.help.v1", ok: true, commands: ["setup buyer", "setup renew", "setup session", "init", "doctor", "status", "wallet", "offer", "pay", "memory", "capability", "audit"], setup: "Run supercuts setup buyer --home <private-directory> for guided live Testnet setup. Run supercuts init --role <buyer|seller|auditor> --mock --home <private-directory> for a local non-funded profile. Keep each role in a separate owner-only home.", live: "Supply the pinned Testnet deployment config, owner-only credential files, Sui and Tatum RPC endpoints, Walrus endpoints, local proving artifacts, and RapidSnark. Fund only the buyer address printed by supercuts-demo setup." })}\n`);
+        process.stdout.write(`${JSON.stringify({ schemaVersion: "supercuts.help.v1", ok: true, commands: ["onboard buyer", "funding prepare", "funding execute", "seller package", "setup buyer", "setup renew", "setup session", "init", "doctor", "status", "wallet", "offer", "pay", "memory", "capability", "audit"], setup: "Run supercuts onboard buyer --home <private-directory> for guided live Testnet setup. Use seller package to validate and prepare an operator-assisted hosted seller bundle.", live: "Use funding prepare to calculate public gas/payment and shielded deposit requirements. Funding execute requires explicit confirmation and funds only the generated buyer address." })}\n`);
         process.exit(0);
     }
     const args = parseArgs(words);
     const home = homePath(args);
-    const result = command === "init" ? initialize(home, args) : command === "setup.buyer" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: typeof args.config === "string" ? setupBuyer(home, args.config) : await promptBuyerSetup(home) } : command === "setup.renew" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: renewBuyer(home, String(args.config ?? "")) } : command === "setup.session" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: createBuyerSession(home) } : command === "policy.add" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: await addBuyerPrivacyRule(home, String(args["capability-id"] ?? "")) } : command === "policy.approve-seller" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: await approveBuyerSeller(home, String(args["capability-id"] ?? "")) } : command === "onboarding.doctor" ? { schemaVersion: "supercuts.onboarding.v1", ok: true, command, data: await onboardingDoctor(home, typeof args.config === "string" ? args.config : undefined) } : await (async () => { const app = new Phase3App(home); try {
+    const fundingInput = { publicPayment: String(args["public-payment"] ?? "0"), shieldedPayment: String(args["shielded-payment"] ?? "0"), ...(typeof args["gas-reserve"] === "string" ? { gasReserve: args["gas-reserve"] } : {}), ...(typeof args["change-reserve"] === "string" ? { changeReserve: args["change-reserve"] } : {}) };
+    const result = command === "init" ? initialize(home, args) : command === "setup.buyer" || command === "onboard.buyer" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: typeof args.config === "string" ? setupBuyer(home, args.config) : await promptBuyerSetup(home) } : command === "setup.renew" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: renewBuyer(home, String(args.config ?? "")) } : command === "setup.session" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: createBuyerSession(home) } : command === "funding.prepare" ? { schemaVersion: "supercuts.funding.v1", ok: true, command, data: await prepareFunding(home, fundingInput) } : command === "funding.execute" ? { schemaVersion: "supercuts.funding.v1", ok: true, command, data: await executeFunding(home, { ...fundingInput, operationId: String(args["operation-id"] ?? ""), requestFaucet: args["request-faucet"] === true, confirmed: args.confirm === true }) } : command === "seller.package" ? { schemaVersion: "supercuts.seller-package.v1", ok: true, command, data: await packageHostedSeller({ home, spec: String(args.spec ?? ""), artifact: String(args.artifact ?? ""), metadata: String(args.metadata ?? ""), registration: String(args.registration ?? ""), bundle: String(args.bundle ?? ""), ...(typeof args["content-type"] === "string" ? { contentType: args["content-type"] } : {}) }) } : command === "policy.add" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: await addBuyerPrivacyRule(home, String(args["capability-id"] ?? "")) } : command === "policy.approve-seller" ? { schemaVersion: "supercuts.setup.v1", ok: true, command, data: await approveBuyerSeller(home, String(args["capability-id"] ?? "")) } : command === "onboarding.doctor" ? { schemaVersion: "supercuts.onboarding.v1", ok: true, command, data: await onboardingDoctor(home, typeof args.config === "string" ? args.config : undefined) } : await (async () => { const app = new Phase3App(home); try {
         return await app.execute(command, args);
     }
     finally {

package/dist/demo.js

@@ -23,6 +23,7 @@ const value = (name, fallback) => typeof args[name] === "string" ? args[name] :
 const stateDir = () => resolve(value("state-dir", ".supercuts-demo"));
 const homes = (root) => ({ buyer: join(root, "buyer"), publicSeller: join(root, "public-seller"), secondPublicSeller: join(root, "second-public-seller"), confidentialSeller: join(root, "confidential-seller"), auditor: join(root, "auditor") });
 const send = (data) => process.stdout.write(`${JSON.stringify({ schemaVersion: "supercuts.demo.v1", ok: true, command, data })}\n`);
+const help = () => ({ commands: ["setup", "doctor", "seed-policy", "reuse-memories", "live", "replay", "check"], setup: "Run supercuts-demo setup --state-dir <owner-only-directory> with the pinned live configuration. Fund only the buyer address in funding[0].address.", live: "The live demo uses Sui Testnet and Mainnet-backed Walrus services; mock receipts are never settlement evidence." });
 function keyAddress(path) { const decoded = decodeSuiPrivateKey(readFileSync(path, "utf8").trim()); if (decoded.scheme !== "ED25519")
     fail("SIGNER_UNSUPPORTED", "demo requires ED25519 Sui keys"); return Ed25519Keypair.fromSecretKey(decoded.secretKey).toSuiAddress(); }
 function createKey(path) { if (!existsSync(path))
@@ -48,20 +49,51 @@ async function setup() {
             fail("DEMO_ROLE_PROFILE_MISMATCH", "demo setup needs fresh isolated live v2 role homes; choose a new --state-dir instead of reusing v1 or mock profiles");
     }
     const workflowPath = typeof args.workflow === "string" ? resolve(args.workflow) : !mock && typeof args["seller-url"] !== "string" ? resolve(value("workflow")) : undefined;
+    let activeCapabilities = [];
     if (workflowPath) {
-        const workflow = JSON.parse(readFileSync(workflowPath, "utf8")), capabilities = workflow.capabilities ?? [];
-        if (!capabilities.length)
+        const workflow = JSON.parse(readFileSync(workflowPath, "utf8")), configured = workflow.capabilities ?? [];
+        if (!configured.length)
             fail("DEMO_CAPABILITIES_REQUIRED", "live workflow must provide capability manifests for the buyer mandate");
-        for (const manifest of capabilities)
+        for (const manifest of configured)
             validateCapabilityManifest(manifest);
+        let capabilities = configured;
+        if (!mock && typeof args["seller-url"] === "string") {
+            const response = await fetch(new URL("/v1/catalog", new URL(args["seller-url"])), { signal: AbortSignal.timeout(90_000) });
+            if (!response.ok)
+                fail("SELLER_SERVICE_UNAVAILABLE", `remote seller catalog returned ${response.status}`);
+            const served = await response.json();
+            const allowedIds = new Set(configured.map((item) => item.capabilityId)), entries = (served.capabilities ?? []).filter((item) => item.manifest && allowedIds.has(item.manifest.capabilityId));
+            if (!entries.length || entries.some((item) => !item.manifest || typeof item.blobId !== "string"))
+                fail("SELLER_CATALOG_INVALID", "remote seller catalog has no configured capabilities with Walrus identities");
+            const app = new Phase3App(roles.buyer);
+            try {
+                const discovered = (await app.execute("capability.discover", { "blob-ids": Buffer.from(JSON.stringify(entries.map((item) => item.blobId))).toString("base64url") })).data.capabilities;
+                const verified = new Map(discovered.map((item) => [`${item.capabilityId}:${item.blobId}`, item.manifestHash]));
+                if (entries.some((item) => verified.get(`${item.manifest.capabilityId}:${item.blobId}`) !== item.manifest.manifestHash))
+                    fail("SELLER_CATALOG_INVALID", "remote seller catalog differs from its Walrus manifests");
+            }
+            finally {
+                app.close();
+            }
+            capabilities = entries.map((item) => item.manifest);
+        }
+        activeCapabilities = capabilities;
         const mandatePath = join(roles.buyer, "mandate.json"), mandate = JSON.parse(readFileSync(mandatePath, "utf8"));
         mandate.requireSettlementPlan = true;
         mandate.allowedCommands = [...new Set([...(Array.isArray(mandate.allowedCommands) ? mandate.allowedCommands : []), "settlement.plan"])];
+        mandate.allowedCounterparties = [...new Set(capabilities.map((item) => item.sellerId))];
         mandate.allowedCapabilityIds = [...new Set(capabilities.map((item) => item.capabilityId))];
         mandate.allowedCapabilityClasses = [...new Set(capabilities.map((item) => item.capability))];
         mandate.allowedRails = [...new Set(capabilities.flatMap((item) => item.supportedRails))];
         writeFileSync(mandatePath, `${JSON.stringify(mandate, null, 2)}\n`, { mode: 0o600 });
         chmodSync(mandatePath, 0o600);
+        const buyerProfilePath = join(roles.buyer, "profile.json"), buyerProfile = JSON.parse(readFileSync(buyerProfilePath, "utf8"));
+        if (!buyerProfile.policy)
+            fail("DEMO_ROLE_PROFILE_MISMATCH", "buyer profile has no payment policy");
+        const buyerPolicy = buyerProfile.policy;
+        buyerPolicy.allowedCounterparties = [...new Set(capabilities.map((item) => item.sellerId))];
+        writeFileSync(buyerProfilePath, `${JSON.stringify(buyerProfile, null, 2)}\n`, { mode: 0o600 });
+        chmodSync(buyerProfilePath, 0o600);
     }
     const mcpScript = join(dirname(fileURLToPath(import.meta.url)), "mcp.js");
     const mcp = { mcpServers: Object.fromEntries(Object.entries(roles).map(([name, home]) => [`supercuts-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`, { command: process.execPath, args: [mcpScript], env: { SUPERCUTS_HOME: home } }])) };
@@ -75,8 +107,10 @@ async function setup() {
         writeFileSync(join(root, "buyer-codex.toml"), codex, { mode: 0o600 });
     }
     const remote = typeof args["seller-url"] === "string";
-    writeFileSync(join(root, "run.json"), `${JSON.stringify({ schema: "supercuts.demo.run.v1", createdAt: new Date().toISOString(), runId, ...(remote ? { eventPath } : {}), mock, homes: roles, addresses }, null, 2)}\n`, { mode: 0o600 });
-    return { stateDir: root, mock, funding: mock ? [] : [{ address: addresses.buyer, needs: ["Testnet SUI gas", "configured x402 asset", "shielded deposit value"] }], sellerPayTo: addresses.publicSeller, sellerAddresses: { publicA: addresses.publicSeller, publicB: addresses.secondPublicSeller, analysis: addresses.confidentialSeller }, files: { mcp: join(root, "mcp.json"), run: join(root, "run.json"), events: remote ? eventPath : join(root, "events.jsonl"), ...(remote ? { codex: join(root, "buyer-codex.toml") } : {}) } };
+    writeFileSync(join(root, "run.json"), `${JSON.stringify({ schema: "supercuts.demo.run.v1", createdAt: new Date().toISOString(), runId, ...(remote ? { eventPath, sellerUrl: new URL(String(args["seller-url"])).toString() } : {}), mock, homes: roles, addresses }, null, 2)}\n`, { mode: 0o600 });
+    const publicSellers = activeCapabilities.filter((item) => item.capability === "sui.market-brief"), analysisSeller = activeCapabilities.find((item) => item.capability === "sui.competitor-analysis");
+    const settlementSellers = activeCapabilities.length ? { publicA: publicSellers[0]?.sellerId, publicB: publicSellers[1]?.sellerId, analysis: analysisSeller?.sellerId } : { publicA: addresses.publicSeller, publicB: addresses.secondPublicSeller, analysis: addresses.confidentialSeller };
+    return { stateDir: root, mock, funding: mock ? [] : [{ address: addresses.buyer, needs: ["Testnet SUI gas", "configured x402 asset", "shielded deposit value"] }], sellerPayTo: settlementSellers.publicA, sellerAddresses: settlementSellers, localRoleAddresses: { publicA: addresses.publicSeller, publicB: addresses.secondPublicSeller, analysis: addresses.confidentialSeller, auditor: addresses.auditor }, files: { mcp: join(root, "mcp.json"), run: join(root, "run.json"), events: remote ? eventPath : join(root, "events.jsonl"), ...(remote ? { codex: join(root, "buyer-codex.toml") } : {}) } };
 }
 async function doctor() {
     if (typeof args["buyer-home"] === "string") {
@@ -103,6 +137,11 @@ async function doctor() {
             const report = (await app.execute("doctor", {})).data;
             if (report.readyForDemo === false)
                 fail("DEMO_PREREQUISITES_MISSING", `${name}: ${report.fixes.join(" ")}`);
+            if (name === "buyer") {
+                const mandate = loadMandate(home), profileSellers = [...app.profile.policy.allowedCounterparties].sort(), mandateSellers = [...mandate.allowedCounterparties].sort();
+                if (JSON.stringify(profileSellers) !== JSON.stringify(mandateSellers))
+                    fail("POLICY_COUNTERPARTY_MISMATCH", "buyer mandate and payment profile allow different sellers; rerun setup refresh before funding");
+            }
             reports[name] = report;
         }
         finally {
@@ -114,16 +153,24 @@ async function doctor() {
         const base = new URL(args["seller-url"]), health = await fetch(new URL("/health", base), { signal: AbortSignal.timeout(90_000) }), catalog = await fetch(new URL("/v1/catalog", base), { signal: AbortSignal.timeout(30_000) });
         if (!health.ok || !catalog.ok)
             fail("SELLER_SERVICE_UNAVAILABLE", "remote seller health or catalog check failed");
+        const healthBody = await health.json(), buyerSigner = String(reports.buyer?.signer ?? ""), accessUrl = new URL("/v1/access", base);
+        accessUrl.searchParams.set("buyerAddress", buyerSigner);
+        const access = await fetch(accessUrl, { signal: AbortSignal.timeout(30_000) });
+        if (!access.ok)
+            fail("SELLER_SERVICE_UNAVAILABLE", "remote seller access preflight failed");
+        const accessBody = await access.json();
+        if (accessBody.allowed !== true)
+            fail("SELLER_BUYER_FORBIDDEN", "remote seller does not currently accept this buyer; use open access or complete owner enrollment before funding");
         const body = await catalog.json(), capabilities = body.capabilities ?? [];
         if (capabilities.filter((item) => item.manifest?.capability === "sui.market-brief").length < 2 || !capabilities.some((item) => item.manifest?.capability === "sui.competitor-analysis"))
             fail("SELLER_CATALOG_INVALID", "remote catalog needs two briefs and one competitor analysis");
-        remote = { healthy: true, origin: base.origin, capabilities: capabilities.length };
+        remote = { healthy: true, origin: base.origin, capabilities: capabilities.length, buyerAccess: accessBody.mode ?? healthBody.buyerAccess ?? "unknown", buyerAllowed: true };
     }
     return { healthy: true, roles: reports, isolation: new Set(Object.values(roles)).size === 5, ...(remote ? { remote } : {}) };
 }
 async function seedPolicy() {
     const source = JSON.parse(readFileSync(resolve(value("workflow")), "utf8"));
-    const manifest = source.capabilities?.find((item) => item.capability === "sui.competitor-analysis") ?? fail("DEMO_POLICY_SCOPE_INVALID", "workflow has no competitor analysis capability");
+    let manifest = source.capabilities?.find((item) => item.capability === "sui.competitor-analysis") ?? fail("DEMO_POLICY_SCOPE_INVALID", "workflow has no competitor analysis capability");
     validateCapabilityManifest(manifest);
     if (manifest.capability !== "sui.competitor-analysis")
         fail("DEMO_POLICY_SCOPE_INVALID", "privacy policy must target the competitor analysis capability");
@@ -131,6 +178,21 @@ async function seedPolicy() {
     try {
         if (app.profile.mock)
             fail("LIVE_PROFILE_REQUIRED", "saved demo privacy policy requires a live buyer profile");
+        const runPath = join(stateDir(), "run.json"), run = existsSync(runPath) ? JSON.parse(readFileSync(runPath, "utf8")) : {};
+        if (run.sellerUrl) {
+            const response = await fetch(new URL("/v1/catalog", run.sellerUrl), { signal: AbortSignal.timeout(90_000) });
+            if (!response.ok)
+                fail("SELLER_SERVICE_UNAVAILABLE", `remote seller catalog returned ${response.status}`);
+            const body = await response.json();
+            const entry = body.capabilities?.find((item) => item.manifest?.capabilityId === manifest.capabilityId && item.manifest.capability === "sui.competitor-analysis") ?? fail("DEMO_POLICY_SCOPE_INVALID", "remote catalog has no matching competitor analysis capability");
+            if (!entry.manifest || typeof entry.blobId !== "string")
+                fail("SELLER_CATALOG_INVALID", "remote analysis capability has no Walrus identity");
+            const liveManifest = entry.manifest, liveBlobId = entry.blobId;
+            const discovered = (await app.execute("capability.discover", { "blob-ids": Buffer.from(JSON.stringify([liveBlobId])).toString("base64url") })).data.capabilities;
+            if (discovered.length !== 1 || discovered[0].blobId !== liveBlobId || discovered[0].manifestHash !== liveManifest.manifestHash)
+                fail("SELLER_CATALOG_INVALID", "remote analysis capability differs from its Walrus manifest");
+            manifest = liveManifest;
+        }
         const memory = { version: "supercuts.settlement-memory.v1", kind: "privacy_rule", scope: { capabilityId: manifest.capabilityId, counterparty: manifest.sellerId, network: "sui:testnet", asset: manifest.asset }, createdAt: Date.now(), signal: { requiresShielded: true } };
         const parameters = { "operation-id": value("operation-id", `privacy-${manifest.capabilityId}`), memory: Buffer.from(JSON.stringify(memory)).toString("base64url") };
         const token = app.approve(app.preview("memory.policy", parameters).challengeId);
@@ -440,7 +502,7 @@ async function replay() {
     return { label: "recorded funded run", freshTransaction: false, events };
 }
 try {
-    const data = command === "setup" ? await setup() : command === "doctor" ? await doctor() : command === "seed-policy" ? await seedPolicy() : command === "reuse-memories" ? reuseMemories() : command === "check" ? await check() : command === "live" ? await live() : command === "replay" ? await replay() : fail("COMMAND_UNKNOWN", "use setup, doctor, seed-policy, reuse-memories, live, replay, or check");
+    const data = ["help", "--help", "-h"].includes(command) ? help() : command === "setup" ? await setup() : command === "doctor" ? await doctor() : command === "seed-policy" ? await seedPolicy() : command === "reuse-memories" ? reuseMemories() : command === "check" ? await check() : command === "live" ? await live() : command === "replay" ? await replay() : fail("COMMAND_UNKNOWN", "use setup, doctor, seed-policy, reuse-memories, live, replay, or check");
     send(data);
 }
 catch (error) {

package/dist/funding.d.ts

@@ -0,0 +1,38 @@
+export interface FundingPlan {
+    address: string;
+    publicBalanceMist: string;
+    shieldedBalanceMist: string;
+    publicPaymentMist: string;
+    shieldedPaymentMist: string;
+    gasReserveMist: string;
+    changeReserveMist: string;
+    poolDepositMist: string;
+    requiredPublicMist: string;
+    publicShortfallMist: string;
+    faucetRequired: boolean;
+    depositRequired: boolean;
+}
+export declare function calculateFundingPlan(input: {
+    address: string;
+    publicBalance: bigint;
+    shieldedBalance: bigint;
+    publicPayment: bigint;
+    shieldedPayment: bigint;
+    gasReserve: bigint;
+    changeReserve: bigint;
+}): FundingPlan;
+export declare function prepareFunding(home: string, values: {
+    publicPayment: string;
+    shieldedPayment: string;
+    gasReserve?: string;
+    changeReserve?: string;
+}): Promise<FundingPlan>;
+export declare function executeFunding(home: string, values: {
+    publicPayment: string;
+    shieldedPayment: string;
+    gasReserve?: string;
+    changeReserve?: string;
+    operationId: string;
+    requestFaucet: boolean;
+    confirmed: boolean;
+}): Promise<Record<string, unknown>>;

package/dist/funding.js

@@ -0,0 +1,78 @@
+import { execFileSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { fail } from "./errors.js";
+import { Phase3App } from "./phase3.js";
+import { writeClient } from "./sui.js";
+const amount = (value, name) => /^[0-9]+$/.test(value) ? BigInt(value) : fail("FUNDING_INPUT_INVALID", `${name} must be unsigned MIST`);
+const POOL_DEPOSIT_DENOMINATIONS = [10000000n, 100000000n];
+const standardPoolDeposit = (shortfall) => {
+    if (shortfall === 0n)
+        return 0n;
+    const denomination = POOL_DEPOSIT_DENOMINATIONS.find((candidate) => candidate >= shortfall);
+    return denomination ?? fail("FUNDING_PLAN_UNSUPPORTED", `shielded funding needs ${shortfall} MIST, above the largest supported single deposit of ${POOL_DEPOSIT_DENOMINATIONS.at(-1)} MIST`);
+};
+export function calculateFundingPlan(input) {
+    const shieldedTarget = input.shieldedPayment > 0n ? input.shieldedPayment + input.changeReserve : 0n;
+    const poolShortfall = shieldedTarget > input.shieldedBalance ? shieldedTarget - input.shieldedBalance : 0n;
+    const poolDeposit = standardPoolDeposit(poolShortfall);
+    const requiredPublic = input.publicPayment + poolDeposit + input.gasReserve;
+    const publicShortfall = requiredPublic > input.publicBalance ? requiredPublic - input.publicBalance : 0n;
+    return { address: input.address, publicBalanceMist: input.publicBalance.toString(), shieldedBalanceMist: input.shieldedBalance.toString(), publicPaymentMist: input.publicPayment.toString(), shieldedPaymentMist: input.shieldedPayment.toString(), gasReserveMist: input.gasReserve.toString(), changeReserveMist: input.changeReserve.toString(), poolDepositMist: poolDeposit.toString(), requiredPublicMist: requiredPublic.toString(), publicShortfallMist: publicShortfall.toString(), faucetRequired: publicShortfall > 0n, depositRequired: poolDeposit > 0n };
+}
+export async function prepareFunding(home, values) {
+    const publicPayment = amount(values.publicPayment, "public payment"), shieldedPayment = amount(values.shieldedPayment, "shielded payment");
+    const gasReserve = amount(values.gasReserve ?? "100000000", "gas reserve"), changeReserve = amount(values.changeReserve ?? "1000000", "change reserve");
+    const app = new Phase3App(home);
+    try {
+        if (app.profile.role !== "buyer" || app.profile.mock)
+            fail("LIVE_PROFILE_REQUIRED", "funding requires a live buyer role home");
+        const doctor = await app.execute("doctor", {}), address = String(doctor.data.signer ?? "");
+        const endpoint = app.profile.live?.writeGrpcEndpoint ?? fail("LIVE_PROFILE_INVALID", "buyer write RPC is missing");
+        const [{ balance }, shielded] = await Promise.all([writeClient(endpoint).getBalance({ owner: address, coinType: "0x2::sui::SUI" }), app.execute("wallet.balance", {})]);
+        return calculateFundingPlan({ address, publicBalance: BigInt(balance.balance), shieldedBalance: BigInt(String(shielded.data.available ?? "0")), publicPayment, shieldedPayment, gasReserve, changeReserve });
+    }
+    finally {
+        app.close();
+    }
+}
+export async function executeFunding(home, values) {
+    if (!values.confirmed)
+        fail("FUNDING_CONFIRMATION_REQUIRED", "funding execution requires --confirm after reviewing the plan");
+    let plan = await prepareFunding(home, values);
+    if (plan.faucetRequired) {
+        if (!values.requestFaucet)
+            fail("BUYER_FUNDING_REQUIRED", `buyer needs ${plan.publicShortfallMist} additional MIST; rerun with --request-faucet --confirm or fund ${plan.address} manually`);
+        execFileSync("sui", ["client", "faucet", "--url", "https://faucet.testnet.sui.io", "--address", plan.address], { stdio: "inherit" });
+        for (let attempt = 0; attempt < 15; attempt++) {
+            await new Promise((resolve) => setTimeout(resolve, 2_000));
+            plan = await prepareFunding(home, values);
+            if (!plan.faucetRequired)
+                break;
+        }
+        if (plan.faucetRequired)
+            fail("FAUCET_ALLOCATION_INSUFFICIENT", `the public faucet allocation did not reach the required ${plan.requiredPublicMist} MIST; wait for finality and inspect funding status before requesting another allocation`);
+    }
+    if (!plan.depositRequired)
+        return { funded: true, faucetRequested: values.requestFaucet, deposit: "not-required", plan };
+    if (!values.operationId)
+        fail("ARGUMENT_REQUIRED", "funding execute requires --operation-id for safe retry");
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        if (process.stdin.isTTY) {
+            const answer = (await rl.question(`Deposit ${plan.poolDepositMist} MIST into the experimental Testnet pool? type yes: `)).trim().toLowerCase();
+            if (answer !== "yes")
+                fail("FUNDING_CANCELLED", "pool deposit was not confirmed");
+        }
+    }
+    finally {
+        rl.close();
+    }
+    const app = new Phase3App(home);
+    try {
+        const deposit = await app.execute("wallet.deposit", { amount: plan.poolDepositMist, "operation-id": values.operationId, authorize: true });
+        return { funded: true, faucetRequested: values.requestFaucet, deposit: deposit.data, plan: await prepareFunding(home, values) };
+    }
+    finally {
+        app.close();
+    }
+}

package/dist/live-runtime.d.ts

@@ -5,6 +5,8 @@ import { Groth16Prover, type ProverConfig } from "./prover.js";
 import { type QueuedExit } from "./v2-exits.js";
 import { TatumLedger } from "./tatum.js";
 import type { RoleStore } from "./store.js";
+export declare function x402ResourceFailure(status: number, response: Uint8Array): string;
+export declare function timestampExpirationUnsupported(value: unknown): boolean;
 export interface LiveRuntimeProfile {
     role: "buyer" | "seller" | "auditor";
     packageId: string;
@@ -52,6 +54,7 @@ export declare class LiveRuntime {
     private existingSigned;
     private submit;
     private confirmTatum;
+    paymentStatus(operationId: string, reconcile?: boolean): Promise<Record<string, unknown>>;
     private prepareOpening;
     deposit(amount: bigint, operationId: string): Promise<Record<string, unknown>>;
     recover(): Promise<Record<string, unknown>>;

package/dist/live-runtime.js

@@ -10,6 +10,38 @@ import { buildDeposit, buildPrivateTransfer, buildWithdraw, writeClient } from "
 import { V2ExitQueue } from "./v2-exits.js";
 import { TatumLedger } from "./tatum.js";
 import { paymentBindingBytes, requirementsHash } from "./x402.js";
+export function x402ResourceFailure(status, response) {
+    const fallback = `paid resource returned ${status}`;
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(response).toString("utf8"));
+    }
+    catch {
+        return fallback;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return fallback;
+    const record = value, code = typeof record.error === "string" ? record.error.replace(/\s+/g, " ").slice(0, 128) : "", message = typeof record.message === "string" ? record.message.replace(/\s+/g, " ").slice(0, 512) : "";
+    return code || message ? `${fallback}: ${[code, message].filter(Boolean).join(": ")}` : fallback;
+}
+export function timestampExpirationUnsupported(value) {
+    const messages = [];
+    const visit = (item, depth = 0) => {
+        if (depth > 3 || item == null)
+            return;
+        if (typeof item === "string")
+            messages.push(item);
+        else if (item instanceof Error) {
+            messages.push(item.message);
+            visit(item.cause, depth + 1);
+        }
+        else if (typeof item === "object")
+            for (const nested of Object.values(item))
+                visit(nested, depth + 1);
+    };
+    visit(value);
+    return messages.some((message) => /timestamp-based transaction expiration is not yet supported|timestamp.*expiration.*not supported/i.test(message));
+}
 const hex = (value) => value.toString(16).padStart(64, "0");
 const bytes32 = (value) => Buffer.from(hex(value), "hex");
 const hash = (value) => createHash("sha256").update(value).digest("hex");
@@ -87,7 +119,7 @@ export class LiveRuntime {
         }
         if (this.profile.role === "buyer" && !this.store.getSecret("live:memory-config"))
             fixes.push("Configure an owner-only Walrus Memory file using the local 1536-dimensional embedding adapter.");
-        return { healthy: true, readyForDemo: fixes.length === 0, fixes, runtime: "testnet-live", signer: this.signer.toSuiAddress(), babyJubPublicKey: identity.publicKey.map(String), x25519PublicKey: this.store.getSecret("identity:x25519-public")?.toString("base64"), rapidSnark: artifacts.rapidSnark, artifacts: artifacts.artifacts, poolObjectVerified: true, tatumServiceVerified: true };
+        return { role: this.profile.role, network: "testnet", packageId: this.profile.packageId, poolId: this.profile.poolId, asset: this.profile.coinType, verifierVersion: this.profile.verifierVersion, keyPermissions: "owner-only", rpc: this.profile.live.writeGrpcEndpoint, healthy: true, readyForDemo: fixes.length === 0, fixes, runtime: "testnet-live", signer: this.signer.toSuiAddress(), babyJubPublicKey: identity.publicKey.map(String), x25519PublicKey: this.store.getSecret("identity:x25519-public")?.toString("base64"), rapidSnark: artifacts.rapidSnark, artifacts: artifacts.artifacts, poolObjectVerified: true, tatumServiceVerified: true };
     }
     async balance() {
         const state = await this.index.sync();
@@ -165,6 +197,29 @@ export class LiveRuntime {
     async confirmTatum(digest, checkpoint) {
         assertTatumFinality(await this.tatum.getTransaction(digest), digest, checkpoint);
     }
+    async paymentStatus(operationId, reconcile = false) {
+        const row = this.store.db.prepare("SELECT digest,status,updated_at AS updatedAt FROM live_signed_transactions WHERE operation_id=?").get(operationId);
+        if (!row)
+            fail("OPERATION_NOT_FOUND", "payment operation was not found in the live transaction journal");
+        const payment = row;
+        const context = this.store.db.prepare("SELECT kind FROM live_operation_context WHERE operation_id=?").get(operationId);
+        const delivered = Boolean(this.store.db.prepare("SELECT 1 FROM live_x402_deliveries WHERE operation_id=?").get(operationId));
+        if (payment.status === "finalized")
+            return { operationId, status: "finalized", transactionDigest: payment.digest, kind: context?.kind ?? "unknown", deliveryStatus: delivered ? "delivered" : "not-applicable-or-pending", finalized: true, safeToResumeSameOperationId: true };
+        if (!reconcile)
+            return { operationId, status: payment.status, transactionDigest: payment.digest, kind: context?.kind ?? "unknown", deliveryStatus: delivered ? "delivered" : "pending", finalized: false, chainStatus: "unchecked", safeToResumeSameOperationId: true };
+        let transaction;
+        try {
+            transaction = await this.client.waitForTransaction({ digest: payment.digest, timeout: 5_000, include: { effects: true } });
+        }
+        catch {
+            return { operationId, status: payment.status, transactionDigest: payment.digest, kind: context?.kind ?? "unknown", deliveryStatus: delivered ? "delivered" : "pending", finalized: false, chainStatus: "not-found-or-pending", safeToResumeSameOperationId: true };
+        }
+        const checkpoint = assertSuiFinality(transaction, payment.digest);
+        await this.confirmTatum(payment.digest, checkpoint);
+        this.store.db.prepare("UPDATE live_signed_transactions SET status='finalized',updated_at=? WHERE operation_id=?").run(Date.now(), operationId);
+        return { operationId, status: "finalized", transactionDigest: payment.digest, kind: context?.kind ?? "unknown", deliveryStatus: delivered ? "delivered" : "pending", finalized: true, checkpoint, tatumVerified: true, safeToResumeSameOperationId: true };
+    }
     prepareOpening(opening, role, operationId, leaves) {
         const commitment = hex(opening.commitment), key = `note:${commitment}`;
         this.store.db.exec("BEGIN IMMEDIATE");
@@ -534,21 +589,40 @@ export class LiveRuntime {
             fail("POLICY_ASSET_FORBIDDEN", "challenged asset is not allowed");
         if (!this.profile.policy.allowedCounterparties.includes(payTo))
             fail("POLICY_COUNTERPARTY_FORBIDDEN", "challenged payee is not allowed");
-        const extra = requirements.extra, requestId = String(extra?.requestId ?? operationId), challengeOperationId = String(extra?.operationId ?? operationId), nonce = String(extra?.nonce ?? "");
-        if (challengeOperationId !== operationId || !nonce || String(extra?.requirementsHash ?? "") !== requirementsHash({ ...requirements, extra: { requestId, operationId: challengeOperationId, nonce } }))
-            fail("X402_CHALLENGE_INVALID", "challenge does not bind this operation and request");
+        const extra = requirements.extra, requestId = String(extra?.requestId ?? operationId), challengeOperationId = String(extra?.operationId ?? operationId), nonce = String(extra?.nonce ?? ""), expiresAt = Number(extra?.expiresAt);
+        const unsignedRequirements = { ...requirements, extra: { requestId, operationId: challengeOperationId, nonce, expiresAt } };
+        if (challengeOperationId !== operationId || !nonce || !Number.isSafeInteger(expiresAt) || expiresAt <= Date.now() || String(extra?.requirementsHash ?? "") !== requirementsHash(unsignedRequirements))
+            fail("X402_CHALLENGE_INVALID", "challenge does not bind this operation, request, and expiry");
         bind?.({ amount: amount.toString(), counterparty: payTo, asset, endpoint: resourceUrl, requestId, requirementsHash: String(extra?.requirementsHash) });
         const tx = new (await import("@mysten/sui/transactions")).Transaction();
         tx.transferObjects([tx.coin({ balance: amount, type: asset })], payTo);
+        tx.setSender(this.signer.toSuiAddress());
+        await tx.build({ client: this.client });
+        const resolvedExpiration = tx.getData().expiration;
+        const validity = resolvedExpiration?.$kind === "ValidDuring" ? resolvedExpiration.ValidDuring : fail("X402_TRANSACTION_EXPIRY_INVALID", "Sui did not resolve a bounded transaction validity window");
+        if (validity.minEpoch == null || validity.maxEpoch == null || !validity.chain || validity.nonce == null)
+            fail("X402_TRANSACTION_EXPIRY_INVALID", "Sui resolved an incomplete transaction validity window");
+        tx.setExpiration({ ValidDuring: { minEpoch: validity.minEpoch, maxEpoch: validity.maxEpoch, minTimestamp: validity.minTimestamp ?? null, maxTimestamp: expiresAt, chain: validity.chain, nonce: validity.nonce } });
+        try {
+            const probe = await this.client.simulateTransaction({ transaction: tx, include: { effects: true } });
+            const simulated = probe.Transaction ?? probe.FailedTransaction;
+            if (!simulated?.status.success && timestampExpirationUnsupported(simulated?.status?.error))
+                tx.setExpiration({ ValidDuring: { minEpoch: validity.minEpoch, maxEpoch: validity.maxEpoch, minTimestamp: validity.minTimestamp ?? null, maxTimestamp: null, chain: validity.chain, nonce: validity.nonce } });
+        }
+        catch (error) {
+            if (!timestampExpirationUnsupported(error))
+                throw error;
+            tx.setExpiration({ ValidDuring: { minEpoch: validity.minEpoch, maxEpoch: validity.maxEpoch, minTimestamp: validity.minTimestamp ?? null, maxTimestamp: null, chain: validity.chain, nonce: validity.nonce } });
+        }
         const legacyIntentHash = hash(JSON.stringify({ domain: "supercuts-x402-v2", operationId, resourceUrl, payTo, asset, amount: amount.toString() }));
         const intentHash = hash(JSON.stringify({ domain: "supercuts-x402-v2", operationId, resourceUrl, payTo, asset, amount: amount.toString(), requestId, requirementsHash: String(extra?.requirementsHash) })), signed = await this.signed(operationId, intentHash, tx, legacyIntentHash);
-        const unsignedBinding = { requestId, nonce, requirementsHash: requirementsHash({ ...requirements, extra: { requestId, operationId: challengeOperationId, nonce } }), transactionDigest: signed.digest, payer: this.signer.toSuiAddress() };
+        const unsignedBinding = { requestId, nonce, requirementsHash: requirementsHash(unsignedRequirements), transactionDigest: signed.digest, payer: this.signer.toSuiAddress() };
         const payerSignature = (await this.signer.signPersonalMessage(paymentBindingBytes(unsignedBinding))).signature;
         const paymentPayload = { x402Version: 2, resource, accepted: requirements, payload: { signature: signed.signature, transaction: Buffer.from(signed.transaction).toString("base64") } };
         const paid = await fetch(paymentUrl, { redirect: "error", headers: { "payment-signature": Buffer.from(JSON.stringify(paymentPayload)).toString("base64"), "x-supercuts-binding": Buffer.from(JSON.stringify({ ...unsignedBinding, payerSignature })).toString("base64") }, signal: AbortSignal.timeout(60_000) });
         const response = Buffer.from(await paid.arrayBuffer());
         if (!paid.ok)
-            fail("X402_DELIVERY_FAILED", `paid resource returned ${paid.status}`);
+            fail("X402_DELIVERY_FAILED", x402ResourceFailure(paid.status, response));
         const settlementHeader = paid.headers.get("payment-response") ?? fail("X402_SETTLEMENT_INVALID", "payment-response header is missing");
         let settlement;
         try {

package/dist/mandate.js

@@ -14,8 +14,8 @@ const definitions = {
     "wallet.balance": object({}, [], false, "Read event-derived private-note balance."),
     "wallet.recover": object({ commitment: string("Optional payment-note commitment."), amount: string("Optional matching amount.", { pattern: "^[1-9][0-9]*$" }) }, [], true, "Recover notes from pinned finalized pool events."),
     "wallet.withdraw": object({ commitment: string("Note commitment to spend."), recipient: string("Sui recipient address.") }, ["commitment"], true, "Withdraw one owned shielded note."),
-    "wallet.exit.queue": object({ commitment: string("Recovered note commitment."), amount: string("Public exit amount in MIST.", { pattern: "^[1-9][0-9]*$" }), "exact-exit": boolean("Approve a nonstandard amount that is publicly visible."), "window-start": string("Exit window start as Unix milliseconds."), "window-end": string("Exit window end as Unix milliseconds.") }, ["commitment", "amount", "window-start", "window-end"], true, "Queue a v2 exit with a fresh payout address and owner-selected delayed window."),
-    "wallet.exit.status": object({ "operation-id": string("Queued exit operation ID.") }, ["operation-id"], false, "Read a queued v2 exit without exposing its proof or note opening."),
+    "wallet.exit.queue": object({ commitment: string("Recovered note commitment."), amount: string("Public exit amount in MIST.", { pattern: "^[1-9][0-9]*$" }), "exact-exit": boolean("Approve a nonstandard amount that is publicly visible."), "window-start": string("Exit window start as Unix milliseconds."), "window-end": string("Exit window end as Unix milliseconds.") }, ["commitment", "amount", "window-start", "window-end"], true, "Queue a delayed pool exit to a fresh payout address."),
+    "wallet.exit.status": object({ "operation-id": string("Queued exit operation ID.") }, ["operation-id"], false, "Read a queued pool exit without exposing its proof or note opening."),
     "wallet.exit.finalize": object({ "exit-id": string("Queued exit operation ID."), digest: string("Finalized relayer transaction digest.") }, ["exit-id", "digest"], true, "Verify Sui and Tatum exit evidence and reconcile the owner note journal."),
     "offer.open": object({ session: string("Optional stable negotiation session ID.") }, [], true, "Open a durable negotiation session."),
     "offer.propose": object({ session: string("Negotiation session ID."), revision: string("Positive revision.", { pattern: "^[1-9][0-9]*$" }), terms: string("Plain-language or canonical JSON terms.") }, ["session", "revision", "terms"], true, "Submit an offer revision."),
@@ -24,7 +24,7 @@ const definitions = {
     "offer.show": object({ session: string("Negotiation session ID.") }, ["session"], false, "Read the latest durable offer revision."),
     "pay.quote": object({ rail: string("Requested settlement rail.", { enum: ["x402", "shielded"] }), amount: string("Unsigned base-unit amount.", { pattern: "^[1-9][0-9]*$" }), counterparty: string("Mandate-approved payee."), asset: string("Sui coin type.") }, ["rail", "amount", "counterparty"], false, "Evaluate payment policy without signing."),
     "pay.shielded": object({ session: string("Accepted agreement session."), amount: string("Unsigned base-unit amount.", { pattern: "^[1-9][0-9]*$" }), counterparty: string("Mandate-approved seller."), asset: string("Sui coin type."), "request-id": string("Bound delivery request ID."), "broadcast-only": boolean("Stop after broadcast for recovery testing."), "plan-hash": string("Approved settlement plan hash.", { pattern: "^[0-9a-f]{64}$" }) }, [], true, "Settle one accepted agreement through the experimental shielded pool."),
-    "pay.x402": object({ "resource-url": string("Seller-owned protected resource URL."), amount: string("Unsigned base-unit amount.", { pattern: "^[1-9][0-9]*$" }), counterparty: string("Mandate-approved public payee."), asset: string("Sui coin type."), "request-id": string("Bound delivery request ID."), "broadcast-only": boolean("Stop after broadcast for recovery testing."), "plan-hash": string("Approved settlement plan hash.", { pattern: "^[0-9a-f]{64}$" }) }, [], true, "Complete a standard x402 v2 exact Sui payment challenge."),
+    "pay.x402": object({ "resource-url": string("Seller-owned protected resource URL."), amount: string("Unsigned base-unit amount.", { pattern: "^[1-9][0-9]*$" }), counterparty: string("Mandate-approved public payee."), asset: string("Sui coin type."), "request-id": string("Bound delivery request ID."), "broadcast-only": boolean("Stop after broadcast for recovery testing."), "plan-hash": string("Approved settlement plan hash.", { pattern: "^[0-9a-f]{64}$" }) }, [], true, "Make a public Sui payment through an x402 exact payment challenge."),
     "pay.status": object({ "operation-id": string("Payment operation identity."), reconcile: boolean("Reconcile an ambiguous broadcast.") }, ["operation-id"], false, "Read or reconcile a previously journaled payment."),
     "resource.serve": object({ "request-id": string("Unique request identity."), body: string("Base64-encoded artifact bytes.") }, ["request-id", "body"], true, "Bind one generated artifact to one request."),
     "resource.fetch": object({ "request-id": string("Bound request identity."), "operation-id": string("Finalized payment operation."), response: string("Base64-encoded paid response.") }, ["request-id", "operation-id", "response"], false, "Record delivery separately from payment evidence."),
@@ -43,13 +43,14 @@ const definitions = {
     "deal.delivery": object({ dealId: string("Existing delivered deal ID.") }, ["dealId"], false, "Read a verified paid artifact from the buyer's encrypted journal."),
     "remote.catalog": object({}, [], false, "Discover the signed remote seller catalog through Walrus."),
     "remote.rank-briefs": object({ budget: string("Total budget in MIST.", { pattern: "^[1-9][0-9]*$" }), topic: string("Sui research topic.", { maxLength: 256 }) }, ["budget", "topic"], false, "Compare eligible market briefs with a visible quality and price rubric."),
-    "remote.negotiate": object({ capabilityId: string("Selected capability ID."), sessionId: string("Stable negotiation session ID."), runId: string("Demo run ID."), task: string("Private task summary.", { maxLength: 512 }), opening: string("Opening amount in MIST.", { pattern: "^[1-9][0-9]*$" }), maximum: string("Maximum amount in MIST.", { pattern: "^[1-9][0-9]*$" }), briefHash: string("Purchased brief SHA-256 if analyzing it.", { pattern: "^[0-9a-f]{64}$" }) }, ["capabilityId", "sessionId", "runId", "task", "opening", "maximum"], false, "Exchange an encrypted buyer offer and seller response through Walrus."),
-    "remote.quote": object({ capabilityId: string("Selected capability ID."), operationId: string("Stable public payment operation ID."), requestId: string("Stable artifact request ID."), runId: string("Demo run ID."), task: string("Brief task summary.", { maxLength: 512 }), briefHash: string("Purchased brief SHA-256 for an analysis variant.", { pattern: "^[0-9a-f]{64}$" }) }, ["capabilityId", "operationId", "requestId", "runId", "task"], false, "Ask a remote seller for its exact x402 quote and protected resource URL."),
-    "remote.purchase-brief": object({ capabilityId: string("Selected market brief capability ID."), operationId: string("Stable public payment operation ID."), requestId: string("Stable artifact request ID."), runId: string("Demo run ID."), task: string("Brief task summary.", { maxLength: 512 }), budget: string("Maximum brief spend in MIST.", { pattern: "^[1-9][0-9]*$" }) }, ["capabilityId", "operationId", "requestId", "runId", "task", "budget"], false, "Plan, buy, verify, and deliver the selected market brief through x402."),
-    "remote.agreement": object({ capabilityId: string("Analysis capability ID."), operationId: string("Stable shielded payment operation ID."), sessionId: string("Stable negotiation session ID."), runId: string("Demo run ID."), briefHash: string("Delivered brief SHA-256.", { pattern: "^[0-9a-f]{64}$" }) }, ["capabilityId", "operationId", "sessionId", "runId", "briefHash"], false, "Request and accept a seller-signed analysis agreement bound to the purchased brief and saved privacy rule."),
+    "remote.negotiate": object({ capabilityId: string("Selected capability ID."), sessionId: string("Stable negotiation session ID."), runId: string("Run ID."), task: string("Private task summary.", { maxLength: 512 }), opening: string("Opening amount in MIST.", { pattern: "^[1-9][0-9]*$" }), maximum: string("Maximum amount in MIST.", { pattern: "^[1-9][0-9]*$" }), briefHash: string("Purchased brief SHA-256 if analyzing it.", { pattern: "^[0-9a-f]{64}$" }) }, ["capabilityId", "sessionId", "runId", "task", "opening", "maximum"], false, "Exchange an encrypted buyer offer and seller response through Walrus."),
+    "remote.quote": object({ capabilityId: string("Selected capability ID."), operationId: string("Stable public payment operation ID."), requestId: string("Stable artifact request ID."), runId: string("Run ID."), task: string("Brief task summary.", { maxLength: 512 }), briefHash: string("Purchased brief SHA-256 for an analysis variant.", { pattern: "^[0-9a-f]{64}$" }) }, ["capabilityId", "operationId", "requestId", "runId", "task"], false, "Ask a remote seller for its exact x402 quote and protected resource URL."),
+    "remote.purchase-brief": object({ capabilityId: string("Selected market brief capability ID."), operationId: string("Stable public payment operation ID."), requestId: string("Stable artifact request ID."), runId: string("Run ID."), task: string("Brief task summary.", { maxLength: 512 }), budget: string("Maximum brief spend in MIST.", { pattern: "^[1-9][0-9]*$" }) }, ["capabilityId", "operationId", "requestId", "runId", "task", "budget"], false, "Plan, buy, verify, and deliver the selected market brief through x402."),
+    "remote.agreement": object({ capabilityId: string("Analysis capability ID."), operationId: string("Stable shielded payment operation ID."), sessionId: string("Stable negotiation session ID."), runId: string("Run ID."), briefHash: string("Delivered brief SHA-256.", { pattern: "^[0-9a-f]{64}$" }) }, ["capabilityId", "operationId", "sessionId", "runId", "briefHash"], false, "Request and accept a seller-signed analysis agreement bound to the purchased brief and saved privacy rule."),
     "remote.settle-analysis": object({ sessionId: string("Accepted analysis session ID."), operationId: string("Stable shielded payment operation ID.") }, ["sessionId", "operationId"], false, "Settle the accepted analysis agreement through the approved shielded pool plan."),
     "remote.delivery": object({ sessionId: string("Accepted analysis session ID."), operationId: string("Finalized shielded payment operation ID.") }, ["sessionId", "operationId"], false, "Recover the seller payment and decrypt the delivered analysis."),
-    "remote.events": object({ runId: string("Demo run ID.") }, ["runId"], false, "Read safe remote seller activity for the demo."),
+    "remote.events": object({ runId: string("Run ID.") }, ["runId"], false, "Read redacted remote seller activity for the run."),
+    "remote.research": object({ topic: string("Sui research topic.", { maxLength: 256 }), budget: string("Total workflow budget in MIST.", { pattern: "^[1-9][0-9]*$" }), runId: string("Optional active run ID; normally supplied by the MCP session.") }, ["topic", "budget"], true, "Rank, purchase, and deliver a public Sui brief plus its matching privacy-aware analysis using one resumable operation."),
     disclose: object({ "deal-id": string("Deal scope."), auditor: string("Designated auditor identity."), "payment-digest": string("Finalized payment digest."), "transcript-root": string("Authenticated agreement transcript root.") }, ["deal-id", "auditor", "payment-digest", "transcript-root"], true, "Create a deal- and auditor-scoped disclosure package."),
     "audit.verify": object({ package: string("Seal ciphertext or mock disclosure package."), auditor: string("This auditor identity."), "deal-id": string("Exact deal scope.") }, ["package", "auditor", "deal-id"], false, "Verify agreement and payment only; delivery remains a separate observation."),
 };

package/dist/mcp-bootstrap.js

@@ -12,6 +12,13 @@ if (existsSync(join(home, "profile.json"))) {
 else {
     const send = (value) => process.stdout.write(`${JSON.stringify(value)}\n`);
     const rl = createInterface({ input: process.stdin });
+    let promoting = false;
+    const promote = () => {
+        if (promoting)
+            return;
+        promoting = true;
+        setImmediate(() => { rl.close(); void import("./mcp.js"); });
+    };
     rl.on("line", (line) => {
         if (Buffer.byteLength(line) > 1024 * 1024)
             return send({ jsonrpc: "2.0", id: null, error: { code: -32600, message: "Request exceeds 1 MiB" } });
@@ -29,11 +36,26 @@ else {
         if (request.method === "notifications/initialized")
             return;
         if (request.method === "tools/list")
-            return send({ jsonrpc: "2.0", id: request.id, result: { tools: [{ name: "setup.status", description: "Explain how the owner completes one-time buyer setup locally. Do not request secrets in chat.", inputSchema: { type: "object", properties: {}, additionalProperties: false } }] } });
+            return send({ jsonrpc: "2.0", id: request.id, result: { tools: [
+                        { name: "setup.status", description: "Explain how the owner completes one-time buyer setup locally. Do not request secrets in chat.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+                        { name: "setup.refresh", description: "Reload this MCP connection after the owner completes local setup.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+                    ] } });
         if (request.method === "tools/call" && request.params?.name === "setup.status") {
-            const result = { schemaVersion: "supercuts.setup.v1", ok: true, configured: false, home, nextStep: `Run supercuts setup buyer --home ${JSON.stringify(home)} in a terminal, then restart this MCP connection. The command asks for policy limits, seller origins and local credential file paths. Do not paste keys or tokens into Codex.` };
+            const configured = existsSync(join(home, "profile.json"));
+            const result = { schemaVersion: "supercuts.setup.v1", ok: true, configured, home, nextStep: configured ? "Call setup.refresh to load the configured buyer tools without restarting the connector." : `Run supercuts onboard buyer --home ${JSON.stringify(home)} in a terminal, then call setup.refresh. The command asks for policy limits, seller origins and local credential file paths. Do not paste keys or tokens into Codex.` };
             return send({ jsonrpc: "2.0", id: request.id, result: { content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result } });
         }
+        if (request.method === "tools/call" && request.params?.name === "setup.refresh") {
+            if (!existsSync(join(home, "profile.json"))) {
+                const result = { schemaVersion: "supercuts.setup.v1", ok: false, error: { code: "SETUP_REQUIRED", message: "buyer setup is not complete", recovery: `Run supercuts onboard buyer --home ${JSON.stringify(home)} locally, then retry setup.refresh.` } };
+                return send({ jsonrpc: "2.0", id: request.id, result: { isError: true, content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result } });
+            }
+            const result = { schemaVersion: "supercuts.setup.v1", ok: true, configured: true, reloading: true };
+            send({ jsonrpc: "2.0", id: request.id, result: { content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result } });
+            send({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
+            promote();
+            return;
+        }
         return send({ jsonrpc: "2.0", id: request.id, error: { code: -32601, message: "Method not found" } });
     });
 }