@envarai/envarpay 0.2.0-alpha.1 → 0.2.0-alpha.11

package/dist/commerce/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFileSync, lstatSync, mkdirSync, writeFileSync } from 'node:fs';
+import { readFileSync, lstatSync, mkdirSync, writeFileSync, readdirSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 import { createRequire } from 'node:module';
 import { randomBytes } from 'node:crypto';
@@ -19,12 +19,19 @@ import { CredentialVault } from './vault.js';
 import { X402Gate } from './x402.js';
 import { evmReceiptVerifier, evmSettlementRecovery } from './chain.js';
 import { CommerceError } from './types.js';
+import { createNativeSkillExecutor } from './native-skills.js';
+import { inspectLedger, inspectLocalAlerts } from './operations.js';
+import { setupHermes } from './setup.js';
+import { SkillDiscovery } from './discovery.js';
+import { upgradeDiscovery, configurePayments } from './configure.js';
 const { values, positionals } = parseArgs({ allowPositionals: true, options: {
         config: { type: 'string' }, service: { type: 'string' }, offer: { type: 'string' }, origin: { type: 'string' },
         version: { type: 'boolean' }, help: { type: 'boolean', short: 'h' }, state: { type: 'string' }, credentials: { type: 'string' }, host: { type: 'string' },
         port: { type: 'string' }, directory: { type: 'string' }, 'envar-config': { type: 'string' }, 'envar-credentials': { type: 'string' },
+        after: { type: 'string' }, limit: { type: 'string' }, 'refund-review': { type: 'boolean' }, alerts: { type: 'boolean' }, 'fail-on-alert': { type: 'boolean' }, 'integration-state': { type: 'string' }, 'no-integration': { type: 'boolean' },
+        file: { type: 'string' }, 'docker-container': { type: 'string' }, python: { type: 'string' }, 'hermes-home': { type: 'string' },
     } });
-const usage = 'envarpay init --directory DIR | validate --config seller.json | card --config seller.json --service ID --offer ID --origin URL | serve/buyer-serve --config FILE --credentials FILE --state DB --origin URL';
+const usage = 'envarpay upgrade --directory DIR [--hermes-home PATH] | payments --directory DIR --file receiving.json\nenvarpay setup --file envar-setup.json [--docker-container NAME | --python PATH] [--hermes-home PATH] [--directory DIR]\ninit --directory DIR | inspect --state DB [--after ROW --limit 100 --refund-review] [--alerts --config buyer-policy.json --integration-state DB/--no-integration --fail-on-alert] | validate --config seller.json | card --config seller.json --service ID --offer ID --origin URL | serve/buyer-serve --config FILE --credentials FILE --state DB --origin URL';
 const closers = [];
 function privateFile(path) {
     const stat = lstatSync(path);
@@ -84,6 +91,35 @@ async function run() {
         return;
     }
     const command = positionals[0];
+    if (command === 'upgrade' && values.directory) {
+        upgradeDiscovery(values.directory, values['hermes-home']);
+        return;
+    }
+    if (command === 'payments' && values.directory && values.file) {
+        await configurePayments(values.directory, values.file);
+        return;
+    }
+    if (command === 'setup') {
+        if (!values.file)
+            throw new CommerceError('setup_file', 'Download the setup file from your Agent service page and pass --file PATH');
+        await setupHermes({ file: values.file, directory: values.directory, container: values['docker-container'], python: values.python, home: values['hermes-home'] });
+        return;
+    }
+    if (values.alerts || values['fail-on-alert'] || values['integration-state'] || values['no-integration']) {
+        if (command !== 'inspect' || !values.state || !values.alerts || values['refund-review'] || values.after || values.limit || (values['no-integration'] && values['integration-state']))
+            throw new CommerceError('inspection_view', 'Alert inspection needs inspect --state and --alerts, without pagination or refund review; choose at most one integration source');
+        const report = inspectLocalAlerts(values.state, { policyPath: values.config, integrationPath: values['integration-state'], integrationDisabled: values['no-integration'] });
+        console.log(JSON.stringify(report, null, 2));
+        if (values['fail-on-alert'])
+            process.exitCode = report.recommendedExitCode;
+        return;
+    }
+    if (command === 'inspect' && values.state) {
+        console.log(JSON.stringify(inspectLedger(values.state, Number(values.after ?? 0), Number(values.limit ?? 100), values['refund-review'] ? 'refund-review' : 'attention'), null, 2));
+        return;
+    }
+    if (values['refund-review'])
+        throw new CommerceError('inspection_view', 'Refund review is available only for inspect');
     if ((values['envar-config'] || values['envar-credentials']) && command !== 'serve')
         throw new CommerceError('envar_role', 'Configuration synchronization is available on seller serve only');
     if (Boolean(values['envar-config']) !== Boolean(values['envar-credentials']))
@@ -117,15 +153,36 @@ async function run() {
                 throw new CommerceError('buyer_key', 'Signer file must contain one 32-byte 0x-prefixed private key');
             signer = privateKeyToAccount(key);
         }
-        if (needsMpp && !secrets.mppAdapterModule)
-            throw new CommerceError('mpp_adapter_module', 'MPP peers require an explicit local adapter module for authorized funding and receipt verification');
-        const mpp = needsMpp ? await loadMppAdapter(secrets.mppAdapterModule) : undefined;
+        if (secrets.mppAdapterModule && secrets.mppStripe)
+            throw new CommerceError('mpp_configuration', 'Choose the built-in Stripe issuer or one explicit adapter module');
+        if (needsMpp && !secrets.mppAdapterModule && !secrets.mppStripe)
+            throw new CommerceError('mpp_configuration', 'MPP peers require a configured Stripe issuer or explicit authorized funding adapter');
+        const buyerVault = secrets.vaultKeyFile ? new CredentialVault(join(dirname(values.state), 'buyer-authorizations'), privateFile(secrets.vaultKeyFile)) : undefined;
+        let mpp;
+        if (needsMpp && secrets.mppStripe) {
+            const configured = secrets.mppStripe;
+            if (!configured.secretKeyFile || !configured.sellers || typeof configured.sellers !== 'object' || Array.isArray(configured.sellers))
+                throw new CommerceError('mpp_configuration', 'Stripe issuer and seller read credentials must use private key files');
+            const { createStripeMppBuyer } = await import('./stripe-issuer.js');
+            const adapter = createStripeMppBuyer({
+                payer: configured.payer, mode: configured.mode, issuerAccountId: configured.issuerAccountId,
+                secretKey: privateFile(configured.secretKeyFile).toString('utf8').trim(), paymentMethod: configured.paymentMethod,
+                ...(configured.publishableKey !== undefined ? { publishableKey: configured.publishableKey } : {}),
+                sellers: Object.fromEntries(Object.entries(configured.sellers).map(([id, seller]) => [id, { accountId: seller.accountId, secretKey: privateFile(seller.secretKeyFile).toString('utf8').trim() }])),
+                ...(configured.issuance ? { issuance: configured.issuance } : {}), ...(configured.returnUrl ? { returnUrl: configured.returnUrl } : {}),
+            }, { statePath: values.state + '.stripe-issuer.sqlite3', vault: buyerVault });
+            closers.push(() => adapter.close());
+            await adapter.assertReady();
+            mpp = adapter;
+        }
+        else if (needsMpp)
+            mpp = await loadMppAdapter(secrets.mppAdapterModule);
         const { BuyerStore } = await import('./buyer-store.js');
         const { CommerceBuyer } = await import('./buyer.js');
         const { BuyerManagement, listenBuyerManagement } = await import('./management.js');
         const store = new BuyerStore(values.state);
         closers.push(() => store.close());
-        const buyer = new CommerceBuyer({ policy, store, vault: secrets.vaultKeyFile ? new CredentialVault(join(dirname(values.state), 'buyer-authorizations'), privateFile(secrets.vaultKeyFile)) : undefined,
+        const buyer = new CommerceBuyer({ policy, store, vault: buyerVault,
             signer, mpp, peerTokens: secrets.peerTokens, peerEndpoints: secrets.peerEndpoints,
             ...(needsEvm ? { verifyReceipt: evmReceiptVerifier(secrets.rpcUrls), ...evmSettlementRecovery(secrets.rpcUrls) } : {}) });
         closers.push(() => buyer.stop());
@@ -171,6 +228,10 @@ async function run() {
         syncSettings = JSON.parse(privateFile(values['envar-config']).toString('utf8'));
         if (!syncSettings?.policy)
             throw new CommerceError('envar_configuration', 'Envar settings must include an explicit local policy');
+        if (secrets.skills?.discovery?.enabledFromWeb) {
+            const installed = readdirSync(secrets.skills.skillsDirectory, { withFileTypes: true }).filter(e => e.isDirectory() && !e.isSymbolicLink() && /^[a-z][a-z0-9-]{0,63}$/.test(e.name)).map(e => e.name);
+            syncSettings.policy.allowedServices = [...new Set([...syncSettings.policy.allowedServices, ...installed])];
+        }
         const tokenFile = resolve(values['envar-credentials']);
         privateFile(tokenFile);
         integration = new EnvarIntegration({ policy: syncSettings.policy, stateDirectory: syncSettings.stateDirectory ?? join(dirname(values.state), 'envar-state'), configDirectory: syncSettings.configDirectory ?? join(dirname(values.state), 'envar-configs'), token: () => privateFile(tokenFile).toString('utf8').trim() });
@@ -201,7 +262,7 @@ async function run() {
         if (!secrets.payers || !secrets.rpcUrls)
             throw new CommerceError('x402_configuration', 'x402 requires explicit caller-payer bindings and network RPCs');
         const gate = new X402Gate({ store, vault: vault, payerFor: caller => secrets.payers?.[caller], verifyReceipt: evmReceiptVerifier(secrets.rpcUrls), ...evmSettlementRecovery(secrets.rpcUrls) });
-        await gate.check(Object.values(config.paymentProfiles).filter((p) => p.adapter === 'x402'));
+        await gate.check([...Object.values(config.paymentProfiles).filter((p) => p.adapter === 'x402'), ...(secrets.receivingProfiles ?? [])]);
         gates.x402 = gate;
     }
     if (protocols.has('mpp')) {
@@ -217,7 +278,11 @@ async function run() {
         gates.mpp = gate;
         stripeRecipientFor = ref => gate.merchantRecipient(ref);
     }
-    const upstreams = new PinnedUpstreams(join(dirname(values.state), 'upstream-bindings.json'), secrets.upstreams, secrets.upstreamInputEncoding, fetch, controller.signal);
+    const nativeSkills = secrets.skills ? createNativeSkillExecutor(secrets.skills, values.origin, config.agent.name) : undefined;
+    const discovery = secrets.skills?.discovery?.enabledFromWeb ? new SkillDiscovery(secrets.skills, secrets.skills.discovery, values.origin) : undefined;
+    if (nativeSkills)
+        closers.push(() => nativeSkills.close());
+    const upstreams = new PinnedUpstreams(join(dirname(values.state), 'upstream-bindings.json'), secrets.upstreams ?? {}, secrets.upstreamInputEncoding, fetch, controller.signal, nativeSkills?.execute);
     upstreams.prepare(config, store.catalogHistory().map(entry => entry.service));
     const validateAdapters = (candidate) => {
         for (const profile of Object.values(candidate.paymentProfiles)) {
@@ -242,7 +307,7 @@ async function run() {
         await new Promise(r => setTimeout(r, 50)); });
     let connection;
     if (integration) {
-        connection = new EnvarSellerRuntime({ integration, server, upstreams, pollIntervalMs: syncSettings?.pollIntervalMs, validateConfig: validateAdapters, onError: code => console.error(JSON.stringify({ code, integration: 'envar' })) });
+        connection = new EnvarSellerRuntime({ integration, server, upstreams, pollIntervalMs: syncSettings?.pollIntervalMs, validateConfig: validateAdapters, beforeSync: discovery ? () => discovery.sync(integration, [...Object.values(server.config.paymentProfiles).filter(p => p.adapter === 'x402'), ...(secrets.receivingProfiles ?? [])].map(p => ({ network: p.network, pay_to: p.payTo, facilitator_url: p.facilitatorUrl }))) : undefined, onError: code => console.error(JSON.stringify({ code, integration: 'envar' })) });
         closers.push(() => connection.stop());
     }
     const http = listenCommerce(server, values.origin, values.host ?? '127.0.0.1', port(4020));

package/dist/commerce/client-runtime.d.ts

@@ -4,5 +4,5 @@ export * from './buyer.js';
 export * from './management.js';
 export * from './vault.js';
 export * from './chain.js';
-export type { MppBuyerOptions, MppTokenOperation, MppVerificationContext, MppReceipt } from './mpp-client.js';
+export type { MppAuthenticationAction, MppBuyerOptions, MppTokenOperation, MppVerificationContext, MppReceipt } from './mpp-client.js';
 export * from './peer-proxy.js';

package/dist/commerce/config.d.ts

@@ -1,7 +1,11 @@
-import { type BuyerPolicy, type CommerceConfig, type PaymentProfile } from './types.js';
+import { type BuyerPolicy, type CommerceConfig, type Offer, type PaymentProfile, type Service } from './types.js';
 export declare function atomic(value: string): bigint;
 export declare function validateUrl(value: string, allowPrivate?: boolean): URL;
 export declare function currencyOf(profile: PaymentProfile): string;
+/** Stripe documents sandbox Business Profile IDs as profile_test_<opaque id>. */
+export declare function isStripeProfileId(value: unknown): value is string;
 export declare function digest(value: unknown): string;
+/** Keep legacy quotes unchanged; skill-bound quotes freeze the installed skill revision too. */
+export declare function serviceTermsDigest(configVersion: 1 | 2, service: Service, offer: Offer, profile: PaymentProfile | null): string;
 export declare function loadCommerceConfig(value: unknown): CommerceConfig;
 export declare function loadBuyerPolicy(value: unknown): BuyerPolicy;

package/dist/commerce/config.js

@@ -45,6 +45,10 @@ export function validateUrl(value, allowPrivate = false) {
 export function currencyOf(profile) {
     return profile.adapter === 'x402' ? `${profile.network}/erc20:${profile.asset.toLowerCase()}` : profile.currency;
 }
+/** Stripe documents sandbox Business Profile IDs as profile_test_<opaque id>. */
+export function isStripeProfileId(value) {
+    return typeof value === 'string' && /^profile_(?:test_)?[A-Za-z0-9]{1,120}$/.test(value);
+}
 function assertJson(value) {
     if (typeof value === 'number' && (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value))))
         throw new CommerceError('unsafe_json_number', 'Use strings for integers outside the safe JSON number range');
@@ -64,6 +68,13 @@ export function digest(value) {
         throw new CommerceError('invalid_json', 'Cannot canonicalize input');
     return createHash('sha256').update(serialized).digest('hex');
 }
+/** Keep legacy quotes unchanged; skill-bound quotes freeze the installed skill revision too. */
+export function serviceTermsDigest(configVersion, service, offer, profile) {
+    const terms = { contract: service.contract, offer, profile };
+    return digest(configVersion === 2 && service.execution.type === 'skill'
+        ? { ...terms, skill: { name: service.id, digest: service.execution.skillDigest } }
+        : terms);
+}
 export function loadCommerceConfig(value) {
     if (!sellerValidator(value))
         throw new CommerceError('invalid_config', ajv.errorsText(sellerValidator.errors));
@@ -80,6 +91,13 @@ export function loadCommerceConfig(value) {
         if (services.has(service.id))
             throw new CommerceError('duplicate_service', 'Service IDs must be unique');
         services.add(service.id);
+        if (config.configVersion === 2 && service.execution.type === 'skill') {
+            if (service.id !== service.name)
+                throw new CommerceError('skill_name_mismatch', 'A version 2 service must use the exact installed skill name as its ID and name');
+        }
+        else if (config.configVersion === 1 && service.execution.type !== 'a2a') {
+            throw new CommerceError('legacy_skill_mode', 'Skill-bound services require configVersion 2');
+        }
         validateUrl(service.execution.cardUrl, true);
         noExternalRefs(service.contract.inputSchema);
         const inputAjv = new Ajv2020({ strict: true });
@@ -143,6 +161,24 @@ export function loadBuyerPolicy(value) {
     const ids = new Set();
     for (const peer of policy.peers) {
         validateUrl(peer.cardUrl);
+        if (peer.mode === 'standard-a2a') {
+            const endpoint = validateUrl(peer.endpoint), card = validateUrl(peer.cardUrl);
+            if (endpoint.origin !== card.origin || endpoint.search || endpoint.href !== peer.endpoint || card.href !== peer.cardUrl)
+                throw new CommerceError('standard_peer_endpoint', 'Review an exact same-origin HTTPS A2A endpoint without query parameters');
+            noExternalRefs(peer.localContract.inputSchema);
+            if (JSON.stringify(peer.localContract.inputSchema).length > 512 * 1024)
+                throw new CommerceError('standard_peer_schema', 'Local input schema exceeds 512 KiB');
+            try {
+                const inputAjv = new Ajv2020({ strict: true });
+                addFormats(inputAjv);
+                inputAjv.compile(peer.localContract.inputSchema);
+            }
+            catch {
+                throw new CommerceError('standard_peer_schema', 'Local input schema must be a valid supported JSON Schema');
+            }
+            if (atomic(peer.localContract.amount) > atomic(peer.maxPerPurchase))
+                throw new CommerceError('purchase_limit', 'Locally reviewed standard-peer price exceeds the per-purchase limit');
+        }
         if (ids.has(peer.id))
             throw new CommerceError('duplicate_peer', 'Peer IDs must be unique');
         ids.add(peer.id);
@@ -154,7 +190,7 @@ export function loadBuyerPolicy(value) {
                 throw new CommerceError('invalid_recipient', 'x402 peers require a nonzero EVM recipient and USDC asset');
             peer.recipient = peer.recipient.toLowerCase();
         }
-        else if (peer.currency !== 'usd' || !/^profile_[A-Za-z0-9]+$/.test(peer.recipient))
+        else if (peer.currency !== 'usd' || !isStripeProfileId(peer.recipient))
             throw new CommerceError('invalid_recipient', 'MPP peers require USD and a verified Stripe merchant profile');
         const limit = limits.get(peer.currency);
         if (limit === undefined || atomic(peer.maxPerPurchase) > limit)

package/dist/commerce/configure.d.ts

@@ -0,0 +1,3 @@
+export declare function refreshLauncher(directory: string): void;
+export declare function upgradeDiscovery(directory: string, home?: string): void;
+export declare function configurePayments(directory: string, file: string): Promise<void>;

package/dist/commerce/configure.js

@@ -0,0 +1,158 @@
+import { readFileSync, writeFileSync, lstatSync, existsSync, renameSync, } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import { CommerceError } from "./types.js";
+import { validateUrl, loadCommerceConfig } from "./config.js";
+function read(path) {
+    const s = lstatSync(path);
+    if (!s.isFile() ||
+        s.isSymbolicLink() ||
+        s.size > 1024 * 1024 ||
+        s.mode & 0o077)
+        throw new CommerceError("private_file", "Use an owner-only configuration file");
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function save(path, value) {
+    const temp = path + ".tmp";
+    writeFileSync(temp, JSON.stringify(value, null, 2) + "\n", {
+        mode: 0o600,
+        flag: "wx",
+    });
+    renameSync(temp, path);
+}
+export function refreshLauncher(directory) {
+    const root = resolve(directory), connection = read(join(root, "connection.json")), settingsPath = join(root, "runtime.json");
+    // alpha.10 start scripts recorded the port in generated source. Parse JSON argv only; never evaluate code.
+    let port;
+    if (existsSync(settingsPath))
+        port = read(settingsPath).port;
+    else {
+        const old = readFileSync(join(root, "start.mjs"), "utf8");
+        const array = /spawn\([^\n]*?,(\[[^\n]+\]),\{stdio:/.exec(old)?.[1];
+        if (!array)
+            throw new CommerceError("setup_upgrade", "Cannot infer original start settings. Use serve with original files.");
+        const args = JSON.parse(array);
+        port = Number(args[args.indexOf("--port") + 1]);
+    }
+    if (!Number.isInteger(port) || port < 1024 || port > 65535)
+        throw new CommerceError("setup_port", "Invalid local service port");
+    const args = [
+        fileURLToPath(new URL("./cli.js", import.meta.url)),
+        "serve",
+        "--config",
+        join(root, "seller.json"),
+        "--credentials",
+        join(root, "credentials.json"),
+        "--state",
+        join(root, "seller.sqlite3"),
+        "--origin",
+        new URL(connection.url).origin,
+        "--host",
+        "127.0.0.1",
+        "--port",
+        String(port),
+        "--envar-config",
+        join(root, "envar.json"),
+        "--envar-credentials",
+        join(root, "envar.token"),
+    ];
+    save(settingsPath, { port });
+    const start = join(root, "start.mjs");
+    writeFileSync(start, `import {spawn} from 'node:child_process';\nconst child=spawn(${JSON.stringify(process.execPath)},${JSON.stringify(args)},{stdio:'inherit'});\nfor(const signal of ['SIGTERM','SIGINT'])process.on(signal,()=>child.kill(signal));\nchild.on('exit',code=>process.exit(code??1));\n`, { mode: 0o700 });
+}
+export function upgradeDiscovery(directory, home) {
+    const root = resolve(directory), file = join(root, "credentials.json"), credentials = read(file);
+    if (credentials.skills?.framework !== "hermes")
+        throw new CommerceError("setup_framework", "This discovery setup supports Hermes");
+    const skill = credentials.skills;
+    const hermesHome = home ??
+        skill.discovery?.hermesHome ??
+        (skill.dockerStateDirectory
+            ? dirname(dirname(skill.dockerStateDirectory))
+            : undefined);
+    if (!hermesHome)
+        throw new CommerceError("setup_home", "Pass --hermes-home with your existing Hermes profile directory");
+    credentials.skills.discovery = { hermesHome, enabledFromWeb: true };
+    refreshLauncher(root);
+    save(file, credentials);
+    console.log(`Discovery enabled. Stop the original service with Ctrl+C, then restart:\n${process.execPath} ${JSON.stringify(join(root, "start.mjs"))}\nInstalled Skills will appear privately in Envar. No service is automatically enabled or published.`);
+}
+export async function configurePayments(directory, file) {
+    if (!process.stdin.isTTY)
+        throw new CommerceError("setup_terminal", "Use an interactive terminal to approve receiving configuration");
+    const root = resolve(directory), bundle = JSON.parse(readFileSync(file, "utf8"));
+    const cfg = read(join(root, "seller.json")), auth = read(join(root, "credentials.json")), sync = read(join(root, "envar.json"));
+    const assets = {
+        "eip155:8453": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
+        "eip155:84532": "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
+    };
+    if (bundle.version !== 1 ||
+        bundle.agentId !== sync.policy.agentId ||
+        !assets[bundle.network] ||
+        !/^0x[0-9a-fA-F]{40}$/.test(bundle.payTo) ||
+        BigInt(bundle.payTo) === 0n)
+        throw new CommerceError("payment_setup", "Download receiving settings for this Agent");
+    const prompt = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const ask = async (text, fallback = "") => (await prompt.question(`${text}${fallback ? ` [${fallback}]` : ""}: `)).trim() || fallback;
+    try {
+        console.log(`Receiving account: ${bundle.payTo}\nNetwork: ${bundle.network === "eip155:8453" ? "Base mainnet" : "Base Sepolia testnet"}\nAsset: official USDC. This enables receiving only; it does not send money or create a signing key.`);
+        if ((await ask("Approve this receiving account? (yes/no)", "no")) !== "yes")
+            return;
+        const facilitator = validateUrl(await ask("x402 facilitator HTTPS URL", bundle.facilitatorUrl ?? ""));
+        const rpc = validateUrl(await ask("Network RPC HTTPS URL", bundle.network === "eip155:8453"
+            ? "https://mainnet.base.org"
+            : "https://sepolia.base.org"));
+        const payer = await ask("Authorized buyer wallet address");
+        if (!/^0x[0-9a-fA-F]{40}$/.test(payer) || BigInt(payer) === 0n)
+            throw new CommerceError("payment_setup", "Use the buyer wallet address for this service access credential");
+        const caller = "buyer-" + payer.slice(2).toLowerCase(), token = randomBytes(36).toString("base64url");
+        auth.callers = { ...auth.callers, [token]: caller };
+        auth.payers = { ...auth.payers, [caller]: payer };
+        auth.rpcUrls = { ...auth.rpcUrls, [bundle.network]: rpc.href };
+        auth.vaultKeyFile ??= join(root, "vault.key");
+        if (!existsSync(auth.vaultKeyFile))
+            writeFileSync(auth.vaultKeyFile, randomBytes(32), {
+                mode: 0o600,
+                flag: "wx",
+            });
+        const profile = {
+            adapter: "x402",
+            scheme: "exact",
+            network: bundle.network,
+            asset: assets[bundle.network],
+            payTo: bundle.payTo,
+            facilitatorUrl: facilitator.href,
+        };
+        loadCommerceConfig({
+            ...cfg,
+            paymentProfiles: { ...cfg.paymentProfiles, "setup-receiving": profile },
+        });
+        auth.receivingProfiles = [
+            ...(auth.receivingProfiles ?? []).filter((p) => p.network !== bundle.network),
+            profile,
+        ];
+        sync.policy.allowedX402 = [
+            ...sync.policy.allowedX402.filter((p) => p.network !== bundle.network),
+            {
+                network: bundle.network,
+                asset: assets[bundle.network],
+                payTo: bundle.payTo.toLowerCase(),
+                facilitatorOrigin: facilitator.origin,
+            },
+        ];
+        const accessFile = join(root, caller + ".token");
+        writeFileSync(accessFile, token + "\n", { mode: 0o600 });
+        save(join(root, "credentials.json"), auth);
+        save(join(root, "envar.json"), sync);
+        refreshLauncher(root);
+        console.log(`Receiving configured for ${cfg.agent.name}. Restart the local service using start.mjs, then refresh Envar.\nBuyer service-access token: ${accessFile}\nGive this file only to the authorized buyer. Original wallets, budgets and ledgers were preserved. No payment performed.`);
+    }
+    finally {
+        prompt.close();
+    }
+}

package/dist/commerce/discovery.d.ts

@@ -0,0 +1,23 @@
+import type { NativeSkillSettings } from "./native-skills.js";
+import type { EnvarIntegration } from "./envar.js";
+export interface DiscoverySettings {
+    hermesHome: string;
+    enabledFromWeb: true;
+}
+export declare class SkillDiscovery {
+    private settings;
+    private discovery;
+    private origin;
+    private enabled;
+    private cached;
+    private nextScan;
+    private state;
+    readonly path: string;
+    constructor(settings: NativeSkillSettings, discovery: DiscoverySettings, origin: string);
+    private scan;
+    sync(integration: EnvarIntegration, payments: {
+        network: string;
+        pay_to: string;
+        facilitator_url: string;
+    }[]): Promise<void>;
+}

package/dist/commerce/discovery.js

@@ -0,0 +1,162 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFileSync, writeFileSync, existsSync, mkdtempSync, mkdirSync, renameSync, rmSync, readdirSync, lstatSync, } from "node:fs";
+import { createHash } from 'node:crypto';
+import { join } from "node:path";
+import { createRequire } from "node:module";
+import { prepareTextSkill } from "./setup.js";
+import { readInstalledSkills } from "./native-skills.js";
+const exec = promisify(execFile);
+function packageDigest(root) {
+    const files = [];
+    let size = 0;
+    function walk(folder, prefix = '') {
+        if (prefix.split('/').length > 12)
+            throw Error('skill_size');
+        for (const name of readdirSync(folder).sort()) {
+            const path = join(folder, name), stat = lstatSync(path);
+            if (stat.isSymbolicLink())
+                throw Error('skill_symlink');
+            if (stat.isDirectory()) {
+                walk(path, prefix + name + '/');
+                continue;
+            }
+            if (!stat.isFile() || stat.size > 512 * 1024 || (size += stat.size) > 1024 * 1024 || files.length >= 128)
+                throw Error('skill_size');
+            files.push([prefix + name, createHash('sha256').update(readFileSync(path)).digest('hex')]);
+        }
+    }
+    walk(root);
+    files.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+    const json = JSON.stringify(files).replace(/[\u007f-\uffff]/g, c => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));
+    return createHash('sha256').update(json).digest('hex');
+}
+export class SkillDiscovery {
+    settings;
+    discovery;
+    origin;
+    enabled;
+    cached = [];
+    nextScan = 0;
+    state = "ready";
+    path;
+    constructor(settings, discovery, origin) {
+        this.settings = settings;
+        this.discovery = discovery;
+        this.origin = origin;
+        this.path = join(settings.skillsDirectory, ".source-digests.json");
+        this.enabled = existsSync(this.path)
+            ? JSON.parse(readFileSync(this.path, "utf8"))
+            : {};
+    }
+    async scan() {
+        const code = readFileSync(new URL("../../examples/hermes-skill-inventory.py", import.meta.url), "utf8");
+        const args = ["-c", code, this.discovery.hermesHome];
+        const { stdout } = this.settings.dockerContainer
+            ? await exec("docker", [
+                "exec",
+                this.settings.dockerContainer,
+                this.settings.python,
+                ...args,
+            ], { timeout: 30000, maxBuffer: 1024 * 1024 })
+            : await exec(this.settings.python, args, {
+                timeout: 30000,
+                maxBuffer: 1024 * 1024,
+            });
+        const list = JSON.parse(stdout);
+        if (!Array.isArray(list) ||
+            list.length > 128 ||
+            list.some((s) => !/^[a-z][a-z0-9-]{0,63}$/.test(s.name) ||
+                !/^[0-9a-f]{64}$/.test(s.digest) ||
+                typeof s.path !== "string"))
+            throw Error("inventory");
+        return list;
+    }
+    async sync(integration, payments) {
+        if (Date.now() >= this.nextScan) {
+            this.nextScan = Date.now() + 15000;
+            try {
+                this.cached = await this.scan();
+                this.state = "ready";
+            }
+            catch {
+                this.state = this.settings.dockerContainer
+                    ? "agent_unavailable"
+                    : "scan_failed";
+            }
+        }
+        const active = new Set(readdirSync(this.settings.skillsDirectory, { withFileTypes: true })
+            .filter((x) => x.isDirectory() && !x.name.startsWith("."))
+            .map((x) => x.name));
+        for (const skill of this.cached)
+            if (active.has(skill.name) && !this.enabled[skill.name])
+                this.enabled[skill.name] = skill.digest;
+        if (this.state === "ready")
+            writeFileSync(this.path, JSON.stringify(this.enabled), { mode: 0o600 });
+        const skills = this.cached.map((s) => ({
+            name: s.name,
+            digest: s.digest,
+            description: s.description,
+            status: !s.supported
+                ? "requires_adapter"
+                : active.has(s.name)
+                    ? this.enabled[s.name] && this.enabled[s.name] !== s.digest
+                        ? "updated"
+                        : "enabled"
+                    : "available",
+        }));
+        for (const name of active)
+            if (!skills.some((s) => s.name === name))
+                skills.push({
+                    name,
+                    digest: this.enabled[name] ?? "0".repeat(64),
+                    description: "",
+                    status: "removed",
+                });
+        const result = await integration.reportRuntime({
+            version: createRequire(import.meta.url)("../../package.json").version,
+            card_url: this.origin + "/.well-known/agent-card.json",
+            state: this.state,
+            skills: skills.slice(0, 128),
+            payments: payments
+                .filter((p, i, all) => all.findIndex((x) => JSON.stringify(x) === JSON.stringify(p)) === i)
+                .slice(0, 8),
+        });
+        for (const request of result) {
+            const skill = this.cached.find((s) => s.name === request.name && s.digest === request.digest && s.supported);
+            if (!skill || active.has(skill.name) || this.state !== "ready")
+                continue;
+            // Check source again after the owner's request. Never overwrite a live package.
+            const current = (await this.scan()).find((s) => s.name === skill.name && s.digest === skill.digest && s.supported);
+            if (!current)
+                continue;
+            const stage = mkdtempSync(join(this.settings.skillsDirectory, ".prepare-"));
+            try {
+                let source = skill.path;
+                if (this.settings.dockerContainer) {
+                    source = join(stage, "source");
+                    await exec("docker", ["cp", `${this.settings.dockerContainer}:${skill.path}`, source], { timeout: 30000, maxBuffer: 1024 * 1024 });
+                }
+                if (packageDigest(source) !== skill.digest)
+                    continue;
+                const prepared = join(stage, "prepared");
+                mkdirSync(prepared);
+                prepareTextSkill(source, join(prepared, skill.name), skill.name);
+                readInstalledSkills(prepared, [], this.origin + "/.well-known/agent-card.json");
+                const after = (await this.scan()).find((s) => s.name === skill.name);
+                if (after?.digest !== skill.digest)
+                    continue;
+                renameSync(join(prepared, skill.name), join(this.settings.skillsDirectory, skill.name));
+                this.enabled[skill.name] = skill.digest;
+                writeFileSync(this.path, JSON.stringify(this.enabled), { mode: 0o600 });
+                // This grant includes only the exact installed package explicitly selected in the owner UI.
+                integration.allowInstalledService(skill.name);
+            }
+            finally {
+                rmSync(stage, { recursive: true, force: true });
+            }
+        }
+        for (const name of active)
+            integration.allowInstalledService(name);
+    }
+}

package/dist/commerce/envar-runtime.d.ts

@@ -8,10 +8,11 @@ export declare class PinnedUpstreams {
     private readonly inputEncoding;
     private readonly fetchImpl;
     private readonly signal?;
+    private readonly skills?;
     private bindings;
     private readonly executors;
     readonly execute: ExecuteOrder;
-    constructor(path: string, credentials: Readonly<Record<string, string>>, inputEncoding?: Readonly<Record<string, "data" | "json-text">>, fetchImpl?: typeof fetch, signal?: AbortSignal | undefined);
+    constructor(path: string, credentials: Readonly<Record<string, string>>, inputEncoding?: Readonly<Record<string, "data" | "json-text">>, fetchImpl?: typeof fetch, signal?: AbortSignal | undefined, skills?: ExecuteOrder | undefined);
     prepare(config: CommerceConfig, history?: readonly Service[]): void;
     private executor;
 }
@@ -30,6 +31,7 @@ export interface EnvarSellerRuntimeOptions {
     /** Local payment adapters/merchant credentials must already exist; config sync cannot create them. */
     validateConfig?: (config: CommerceConfig) => void;
     onError?: (code: string) => void;
+    beforeSync?: () => Promise<void>;
 }
 export declare class EnvarSellerRuntime {
     private readonly options;