@envarai/envarpay 0.2.0-alpha.10 → 0.2.0-alpha.12

package/dist/commerce/agent-setup.d.ts

@@ -0,0 +1,18 @@
+interface Invitation {
+    version: 1;
+    agentId: string;
+    platformOrigin: string;
+    setupToken: string;
+}
+export declare function invitation(value: any): Invitation;
+export declare function agentSetup(options: {
+    file: string;
+    directory?: string;
+    python?: string;
+    home?: string;
+    container?: string;
+    origin?: string;
+    port?: number;
+    checkOnly?: boolean;
+}): Promise<void>;
+export {};

package/dist/commerce/agent-setup.js

@@ -0,0 +1,189 @@
+/** Agent-driven installation. Secrets stay in local files; receipts come from Envar. */
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, openSync, closeSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createServer } from 'node:net';
+import { spawn } from 'node:child_process';
+import { setupHermes, parseSetupBundle } from './setup.js';
+import { CommerceError } from './types.js';
+function privateJson(file) {
+    const s = lstatSync(file);
+    if (!s.isFile() || s.isSymbolicLink() || s.size > 16384 || (s.mode & 0o077))
+        throw new CommerceError('setup_private_file', 'Save the setup invitation in an owner-only file (chmod600).');
+    return JSON.parse(readFileSync(file, 'utf8'));
+}
+export function invitation(value) {
+    if (value?.version !== 1 || !/^[0-9a-f-]{36}$/.test(value.agentId) || !/^envar_setup_[A-Za-z0-9_-]{43}$/.test(value.setupToken))
+        throw new CommerceError('setup_invitation', 'Copy a fresh setup prompt.');
+    const url = new URL(value.platformOrigin);
+    if (url.protocol !== 'https:' || url.origin !== value.platformOrigin || url.username || url.password)
+        throw new CommerceError('setup_origin', 'Use the exact Envar HTTPS origin.');
+    return value;
+}
+async function request(invite, path, data) {
+    const r = await fetch(invite.platformOrigin + '/api/v1/agent-setup/' + path, { method: 'POST', redirect: 'error', headers: { Authorization: 'Bearer ' + invite.setupToken, 'Content-Type': 'application/json' }, body: JSON.stringify(data), signal: AbortSignal.timeout(45000) });
+    if (!r.ok)
+        throw new CommerceError('setup_' + path, `Envar ${path} returned ${r.status}. Check connection or copy a fresh prompt; do not report success.`);
+    const text = await r.text();
+    if (text.length > 65536)
+        throw new CommerceError('setup_response', 'Envar returned an oversized response.');
+    return JSON.parse(text);
+}
+async function freePort() {
+    const socket = createServer();
+    await new Promise((resolve, reject) => { socket.once('error', reject); socket.listen(0, '127.0.0.1', resolve); });
+    const port = socket.address().port;
+    await new Promise(resolve => socket.close(() => resolve()));
+    return port;
+}
+function save(file, data) { writeFileSync(file, JSON.stringify(data, null, 2) + '\n', { mode: 0o600, flag: 'wx' }); }
+async function publicOrigin(root, port, agentId, supplied) {
+    if (supplied) {
+        const u = new URL(supplied);
+        if (u.protocol !== 'https:' || u.origin !== supplied)
+            throw Error('Use a public HTTPS origin');
+        return supplied;
+    }
+    // Use an available existing tunnel session, without deleting or rebinding any endpoint.
+    for (const apiPort of [4040, 4041, 4042, 4043]) {
+        try {
+            const api = `http://127.0.0.1:${apiPort}`;
+            const r = await fetch(api + '/api/tunnels', { signal: AbortSignal.timeout(1000) });
+            if (!r.ok)
+                continue;
+            const list = (await r.json());
+            const name = 'envarpay-' + agentId, addr = `http://127.0.0.1:${port}`;
+            const prior = list.tunnels?.find((t) => t.name === name);
+            if (prior) {
+                if (prior.config.addr !== addr)
+                    continue;
+                return prior.public_url;
+            }
+            if (list.tunnels?.length >= 3)
+                continue;
+            const created = await fetch(api + '/api/tunnels', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name, proto: 'http', addr, schemes: ['https'], inspect: false }), signal: AbortSignal.timeout(12000) });
+            if (created.ok)
+                return (await created.json()).public_url;
+        }
+        catch { }
+    }
+    // Outbound HTTPS works inside Docker too; never requires a Docker socket or host port mapping.
+    const log = join(root, 'tunnel.log');
+    if (existsSync(log))
+        privateLog(log);
+    const offset = existsSync(log) ? readFileSync(log, 'utf8').length : 0, fd = openSync(log, 'a', 0o600);
+    const tunnel = spawn('cloudflared', ['tunnel', '--url', `http://127.0.0.1:${port}`, '--no-autoupdate'], { detached: true, stdio: ['ignore', fd, fd] });
+    closeSync(fd);
+    let failed = false;
+    tunnel.on('error', () => { failed = true; });
+    tunnel.unref();
+    for (let i = 0; i < 45; i++) {
+        if (failed)
+            break;
+        await new Promise(resolve => setTimeout(resolve, 1000));
+        const url = readFileSync(log, 'utf8').slice(offset).match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com\b/)?.[0];
+        if (url) {
+            writeFileSync(join(root, 'tunnel-process.json'), JSON.stringify({ pid: tunnel.pid, origin: url, temporary: true }), { mode: 0o600 });
+            return url;
+        }
+    }
+    if (tunnel.pid)
+        try {
+            tunnel.kill();
+        }
+        catch { }
+    throw new CommerceError('setup_https', 'Install cloudflared from its official distribution, or supply --origin with an existing HTTPS forwarder. Preserve other tunnels.');
+}
+function privateLog(file) { const s = lstatSync(file); if (!s.isFile() || s.isSymbolicLink() || (s.mode & 0o077))
+    throw new CommerceError('setup_private_file', 'Runtime log must be an owner-only regular file.'); }
+export async function agentSetup(options) {
+    const invite = invitation(privateJson(resolve(options.file)));
+    const profile = resolve(options.directory ?? join(homedir(), '.envarpay', invite.agentId));
+    const root = profile + '.onboarding';
+    if (options.checkOnly) {
+        const result = await request(invite, 'status', {});
+        if (result.agent_id !== invite.agentId)
+            throw new CommerceError('setup_identity', 'Receipt belongs to another Agent.');
+        console.log(JSON.stringify(result, null, 2));
+        if (result.status !== 'connected')
+            process.exitCode = 1;
+        return;
+    }
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    if (lstatSync(root).isSymbolicLink() || (lstatSync(root).mode & 0o077))
+        throw new CommerceError('setup_directory', 'Use a private directory owned by this user.');
+    const manifest = join(root, 'setup.json');
+    if (existsSync(manifest) && privateJson(manifest).agentId !== invite.agentId)
+        throw new CommerceError('setup_identity', 'This directory belongs to another Agent.');
+    const bundle = parseSetupBundle(await request(invite, 'claim', {}));
+    if (bundle.agentId !== invite.agentId || bundle.platformOrigin !== invite.platformOrigin)
+        throw new CommerceError('setup_identity', 'Envar returned another Agent identity.');
+    const bundleFile = join(root, 'bundle.json');
+    if (existsSync(bundleFile))
+        privateJson(bundleFile);
+    writeFileSync(bundleFile, JSON.stringify(bundle), { mode: 0o600 });
+    if (!existsSync(profile)) {
+        let settings = existsSync(manifest) ? privateJson(manifest) : undefined;
+        if (!settings) {
+            const port = options.port ?? await freePort();
+            const origin = await publicOrigin(root, port, invite.agentId, options.origin);
+            settings = { agentId: invite.agentId, port, origin };
+            save(manifest, settings);
+        }
+        await setupHermes({ file: bundleFile, directory: profile, python: options.python, home: options.home, container: options.container, automatic: settings });
+    }
+    if (lstatSync(profile).isSymbolicLink() || (lstatSync(profile).mode & 0o077))
+        throw new CommerceError('setup_directory', 'The runtime must be a private directory.');
+    const connection = privateJson(join(profile, 'connection.json'));
+    privateLog(join(profile, 'envar.token'));
+    const launcher = lstatSync(join(profile, 'start.mjs'));
+    if (!launcher.isFile() || launcher.isSymbolicLink() || (launcher.mode & 0o077))
+        throw new CommerceError('setup_private_file', 'Use the original private runtime launcher.');
+    if (connection.agentId !== invite.agentId)
+        throw new CommerceError('setup_identity', 'Existing runtime belongs to another Agent.');
+    const policy = privateJson(join(profile, 'envar.json')).policy;
+    if (policy.agentId !== invite.agentId || policy.platformOrigin !== invite.platformOrigin)
+        throw new CommerceError('setup_identity', 'Existing integration belongs to another Agent.');
+    const running = join(root, 'process.json');
+    let started = false;
+    if (existsSync(running))
+        try {
+            process.kill(privateJson(running).pid, 0);
+            started = true;
+        }
+        catch { }
+    if (started && readFileSync(join(profile, 'envar.token'), 'utf8') !== bundle.token)
+        throw new CommerceError('setup_running', 'Existing runtime uses an earlier credential. Stop its recorded process, keep its ledger, then retry this invitation.');
+    if (!started) {
+        privateLog(join(profile, 'envar.token'));
+        writeFileSync(join(profile, 'envar.token'), bundle.token, { mode: 0o600 });
+        const log = join(root, 'runtime.log');
+        if (existsSync(log))
+            privateLog(log);
+        const fd = openSync(log, 'a', 0o600), child = spawn(process.execPath, [join(profile, 'start.mjs')], { detached: true, stdio: ['ignore', fd, fd] });
+        closeSync(fd);
+        child.unref();
+        writeFileSync(running, JSON.stringify({ pid: child.pid }), { mode: 0o600 });
+    }
+    let result;
+    for (let attempt = 0; attempt < 12; attempt++) {
+        try {
+            result = await request(invite, 'connect', { agentId: invite.agentId, url: connection.url, authToken: connection.authToken });
+            if (result.status === 'connected')
+                break;
+        }
+        catch (e) {
+            if (attempt === 11)
+                throw e;
+        }
+        await new Promise(resolve => setTimeout(resolve, 3000));
+    }
+    result = await request(invite, 'status', {});
+    if (result.status !== 'connected' || result.agent_id !== invite.agentId || !result.verified_at)
+        throw new CommerceError('setup_unverified', 'Platform did not verify this setup. Keep files and report the blocker.');
+    const output = { ...result, local_directory: profile, receipt_file: join(root, 'receipt.json'), scope: 'connected; not published; no payment', restart: `node ${JSON.stringify(join(profile, 'start.mjs'))}`, temporary_tunnel: !options.origin, automatic_restart: false };
+    if (existsSync(join(root, 'receipt.json')))
+        privateJson(join(root, 'receipt.json'));
+    writeFileSync(join(root, 'receipt.json'), JSON.stringify(output, null, 2) + '\n', { mode: 0o600 });
+    console.log(JSON.stringify(output, null, 2));
+}

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';
@@ -22,14 +22,17 @@ 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';
+import { agentSetup } from './agent-setup.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' },
+        file: { type: 'string' }, 'docker-container': { type: 'string' }, python: { type: 'string' }, 'hermes-home': { type: 'string' }, check: { type: 'boolean' },
     } });
-const usage = 'envarpay 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 usage = 'envarpay onboard --file invitation.json [--check] [--python PATH] [--docker-container NAME] [--hermes-home PATH] [--origin HTTPS_ORIGIN]\nenvarpay 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);
@@ -89,6 +92,20 @@ async function run() {
         return;
     }
     const command = positionals[0];
+    if (command === 'onboard') {
+        if (!values.file)
+            throw new CommerceError('setup_file', 'Save the private invitation and pass --file PATH.');
+        await agentSetup({ file: values.file, directory: values.directory, python: values.python, home: values['hermes-home'], container: values['docker-container'], origin: values.origin, port: values.port ? port(4020) : undefined, checkOnly: values.check });
+        return;
+    }
+    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');
@@ -218,6 +235,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() });
@@ -248,7 +269,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')) {
@@ -265,6 +286,7 @@ async function run() {
         stripeRecipientFor = ref => gate.merchantRecipient(ref);
     }
     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);
@@ -292,7 +314,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/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

@@ -31,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;

package/dist/commerce/envar-runtime.js

@@ -231,6 +231,13 @@ export class EnvarSellerRuntime {
             return this.running;
         this.running = (async () => {
             try {
+                try {
+                    await this.options.beforeSync?.();
+                }
+                catch {
+                    // A discovery failure must not stall existing service updates or delivery reports.
+                    this.options.onError?.("skill_discovery");
+                }
                 for (const candidate of await this.options.integration.pullCandidates())
                     await this.options.integration.applyCandidate(candidate, (c) => this.apply(c));
             }

package/dist/commerce/envar.d.ts

@@ -81,6 +81,11 @@ export declare class EnvarIntegration {
     close(): void;
     private open;
     private request;
+    allowInstalledService(name: string): void;
+    reportRuntime(value: unknown): Promise<{
+        name: string;
+        digest: string;
+    }[]>;
     private candidate;
     /** Latest locally acknowledged revisions; startup recovery never requires platform connectivity. */
     appliedCandidates(): EnvarCandidate[];

package/dist/commerce/envar.js

@@ -218,6 +218,7 @@ export class EnvarIntegration {
             "/api/v1/agent-config/candidates",
             "/api/v1/agent-config/acknowledgments",
             "/api/v1/commerce-reports",
+            "/api/v1/agent-config/runtime",
         ].includes(path))
             fail("envar_path", "Unsupported platform integration operation");
         const token = await this.options.token();
@@ -297,6 +298,18 @@ export class EnvarIntegration {
             fail("envar_response_json", "Platform response must be an object");
         return value;
     }
+    allowInstalledService(name) {
+        if (!ID.test(name))
+            fail('envar_policy', 'Invalid installed Skill name');
+        if (!this.policy.allowedServices.includes(name))
+            this.policy.allowedServices.push(name);
+    }
+    async reportRuntime(value) {
+        const response = await this.request('/api/v1/agent-config/runtime', value, randomUUID());
+        if (response.agent_id !== this.policy.agentId || !Array.isArray(response.enable) || response.enable.length > 128)
+            fail('envar_inventory', 'Invalid runtime acknowledgment');
+        return response.enable.filter((x) => x && ID.test(x.name) && /^[0-9a-f]{64}$/.test(x.digest));
+    }
     candidate(value) {
         if (!this.policy.acceptUpdates)
             fail("envar_updates_disabled", "Local owner has not enabled platform configuration updates");

package/dist/commerce/native-skills.d.ts

@@ -13,6 +13,10 @@ export interface NativeSkillSettings {
     /** Host-side Docker CLI, never a Docker socket mounted into the Agent. */
     dockerContainer?: string;
     dockerStateDirectory?: string;
+    discovery?: {
+        hermesHome: string;
+        enabledFromWeb: true;
+    };
 }
 interface InstalledSkill {
     descriptor: SkillDescriptor;

package/dist/commerce/native-skills.js

@@ -56,8 +56,8 @@ export function readInstalledSkills(root, freeSkills, cardUrl) {
             throw new CommerceError('skill_size', 'Instruction resources exceed the supported context size');
         output.push({ descriptor: { name, digest: digest(files), cardUrl, access: freeSkills.includes(name) ? 'free' : 'paid', description }, instructions: instructions + references });
     }
-    if (!output.length || output.length > 32 || freeSkills.some(name => !output.some(s => s.descriptor.name === name)))
-        throw new CommerceError('skill_inventory', 'Install between 1 and 32 skills and declare only installed free skills');
+    if (output.length > 32 || freeSkills.some(name => !output.some(s => s.descriptor.name === name)))
+        throw new CommerceError('skill_inventory', 'Install at most 32 skills and declare only installed free skills');
     // Free helpers are executable dependencies of every purchase, so their versions
     // and access-policy changes must invalidate the quote's selected skill digest too.
     const helpers = output.filter(s => s.descriptor.access === 'free').map(s => ({ name: s.descriptor.name, digest: s.descriptor.digest }));
@@ -70,7 +70,7 @@ export function createNativeSkillExecutor(settings, origin, agentName) {
         throw new CommerceError('skill_settings', 'Configure a supported native skill runtime');
     const cardUrl = new URL('/.well-known/agent-card.json', origin).href;
     const installed = () => readInstalledSkills(settings.skillsDirectory, settings.freeSkills, cardUrl);
-    const initial = installed();
+    installed();
     mkdirSync(settings.stateDirectory, { recursive: true, mode: 0o700 });
     const stateStat = lstatSync(settings.stateDirectory);
     if (!stateStat.isDirectory() || stateStat.isSymbolicLink() || (stateStat.mode & 0o077) !== 0)
@@ -170,7 +170,5 @@ export function createNativeSkillExecutor(settings, origin, agentName) {
         const skills = installed();
         return AgentCard.fromJSON({ name: agentName, description: 'Installed Agent Skills', version: '1.0', supportedInterfaces: [{ url: new URL('/a2a', origin).href, protocolBinding: 'JSONRPC', protocolVersion: '1.0' }], capabilities: { extensions: [{ uri: 'urn:envarpay:skill-gate:1', required: false, params: { runtime: 'instruction-only-v1', skills: skills.map(s => ({ name: s.descriptor.name, digest: s.descriptor.digest, access: s.descriptor.access })) } }] }, defaultInputModes: ['application/json'], defaultOutputModes: ['text/markdown'], skills: skills.map(s => ({ id: s.descriptor.name, name: s.descriptor.name, description: s.descriptor.description, tags: [s.descriptor.name] })) });
     };
-    if (initial.length === 0)
-        throw new CommerceError('skill_inventory', 'No installed skills');
     return { execute, close: async () => { await Promise.allSettled(inFlight.values()); db.close(); } };
 }

package/dist/commerce/setup.d.ts

@@ -15,4 +15,8 @@ export declare function setupHermes(options: {
     container?: string;
     python?: string;
     home?: string;
+    automatic?: {
+        port: number;
+        origin: string;
+    };
 }): Promise<void>;

package/dist/commerce/setup.js

@@ -69,18 +69,16 @@ export async function setupHermes(options) {
     const bundle = parseSetupBundle(JSON.parse(readFileSync(file, "utf8")));
     if (options.container && !CONTAINER.test(options.container))
         throw new CommerceError("setup_container", "Use a Docker container name");
-    if (!process.stdin.isTTY)
+    if (!process.stdin.isTTY && !options.automatic)
         throw new CommerceError("setup_terminal", "Run setup in an interactive terminal to select skills");
     chmodSync(file, 0o600);
-    const prompt = createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
+    const prompt = options.automatic ? undefined : createInterface({ input: process.stdin, output: process.stdout });
+    const output = options.automatic ? (..._args) => { } : console.log;
     const ask = async (label, fallback = "") => (await prompt.question(`${label}${fallback ? ` [${fallback}]` : ""}: `)).trim() || fallback;
     let staging;
     try {
-        console.log(`\nConnect ${bundle.agentName} to ${bundle.platformOrigin}\nModel credentials and tasks remain on this machine. Start with free services; no wallet is created.\n`);
-        if ((await ask("Continue? (yes/no)", "no")).toLowerCase() !== "yes")
+        output(`\nConnect ${bundle.agentName} to ${bundle.platformOrigin}\nModel credentials and tasks remain on this machine. Start with free services; no wallet is created.\n`);
+        if (!options.automatic && (await ask("Continue? (yes/no)", "no")).toLowerCase() !== "yes")
             return;
         const directory = resolve(options.directory ?? join(homedir(), ".envarpay", bundle.agentId));
         if (existsSync(directory))
@@ -105,6 +103,18 @@ export async function setupHermes(options) {
             if (!python)
                 throw new CommerceError("setup_runtime", "No compatible Hermes interpreter found in this container. Update Hermes or pass --python PATH.");
         }
+        if (!python && options.automatic) {
+            for (const candidate of [process.env.VIRTUAL_ENV && join(process.env.VIRTUAL_ENV, "bin/python"), "/opt/hermes-latest/bin/python", "/opt/hermes/.venv/bin/python", join(homedir(), "hermes-agent/.venv/bin/python"), "python3"].filter(Boolean)) {
+                try {
+                    execFileSync(candidate, ["-c", compatibility], { stdio: "pipe", timeout: 30000 });
+                    python = candidate;
+                    break;
+                }
+                catch { }
+            }
+            if (!python)
+                throw new CommerceError("setup_runtime", "No compatible Hermes Python found. Pass its executable using --python.");
+        }
         python ??= await ask("Hermes Python executable", join(homedir(), "hermes-agent", ".venv", "bin", "python"));
         const probeSource = readFileSync(new URL("../../examples/hermes-setup-probe.py", import.meta.url), "utf8");
         let probe;
@@ -134,26 +144,25 @@ export async function setupHermes(options) {
             throw new CommerceError("setup_model", "Could not read Hermes. Check the container/Python path and configure an OpenAI-compatible model in Hermes first.");
         }
         const candidates = probe.skills.filter((s) => s.textPackage && ID.test(s.name));
-        console.log(`Model: ${probe.model}\nInstalled text packages (review their instructions before selecting):`);
-        candidates.forEach((skill, i) => console.log(`${i + 1}. ${skill.name} — ${skill.description.replace(/[\r\n\x1b]/g, " ").slice(0, 160)}`));
-        if (!candidates.length)
-            throw new CommerceError("setup_skills", "Install a text skill in Hermes first, then run setup again");
-        const selected = (await ask("Skill names to offer (comma separated)"))
+        output(`Model: ${probe.model}\nInstalled text packages (review their instructions before selecting):`);
+        candidates.forEach((skill, i) => output(`${i + 1}. ${skill.name} — ${skill.description.replace(/[\r\n\x1b]/g, " ").slice(0, 160)}`));
+        output('Newly installed Skills will be discovered privately. Enable each one from the Envar service page after reviewing text-only compatibility.');
+        const selected = (options.automatic ? "" : await ask("Optional: enable existing text Skills now (comma separated, Enter to skip)"))
             .split(",")
-            .map((s) => s.trim());
-        if (!selected.length ||
-            selected.length > 32 ||
+            .map((s) => s.trim()).filter(Boolean);
+        if (selected.length > 32 ||
             new Set(selected).size !== selected.length ||
             selected.some((name) => !candidates.some((s) => s.name === name)))
             throw new CommerceError("setup_skills", "Choose installed skill names from the list");
-        console.log("This adapter supplies buyer text and bundled Markdown references. Browser, script, file and API tools are disabled. Original Hermes skills are preserved; a service copy is created.");
-        if ((await ask("Do these selected skills work with text input and text output only? (yes/no)", "no")).toLowerCase() !== "yes")
+        output("This adapter supplies buyer text and bundled Markdown references. Browser, script, file and API tools are disabled. Original Hermes skills are preserved; a service copy is created.");
+        if (selected.length &&
+            (await ask("Do these selected skills work with text input and text output only? (yes/no)", "no")).toLowerCase() !== "yes")
             return;
-        const port = Number(await ask("Local service port", "4020"));
+        const port = options.automatic?.port ?? Number(await ask("Local service port", "4020"));
         if (!Number.isInteger(port) || port < 1024 || port > 65535)
             throw new CommerceError("setup_port", "Choose a local port from 1024 to 65535");
         let origin;
-        const tunnelMode = await ask("Public HTTPS: use an existing ngrok session or your own reverse proxy? (ngrok/url)", "ngrok");
+        const tunnelMode = options.automatic ? "url" : await ask("Public HTTPS: use an existing ngrok session or your own reverse proxy? (ngrok/url)", "ngrok");
         if (tunnelMode === "ngrok") {
             const api = new URL(await ask("Local ngrok API", "http://127.0.0.1:4040"));
             if (api.protocol !== "http:" ||
@@ -193,7 +202,7 @@ export async function setupHermes(options) {
             }
         }
         else if (tunnelMode === "url") {
-            origin = await ask(`Public HTTPS origin (forward to http://127.0.0.1:${port})`);
+            origin = options.automatic?.origin ?? await ask(`Public HTTPS origin (forward to http://127.0.0.1:${port})`);
         }
         else
             throw new CommerceError("setup_tunnel", "Choose ngrok or url");
@@ -271,6 +280,7 @@ export async function setupHermes(options) {
             upstreams: {},
             skills: {
                 framework: "hermes",
+                discovery: { hermesHome: probe.home, enabledFromWeb: true },
                 skillsDirectory: join(directory, "skills"),
                 freeSkills: [],
                 stateDirectory,
@@ -334,10 +344,10 @@ export async function setupHermes(options) {
         writeFileSync(join(staging, "README.md"), `# ${bundle.agentName}\n\nStart: node ${JSON.stringify(start)}\n\nKeep the terminal, Hermes, and HTTPS tunnel running. Import connection.json in the Envar setup page, then check the connection. Choose a skill and save a free service. Request publication; this process applies the selected service automatically. Return to Envar and check/publish.\n\nOnly free service updates are authorized. Receiving and payment setup is separate. Platform token expires ${bundle.expiresAt}. Keep the original files and ledger when restarting.\n`, { mode: 0o600, flag: "wx" });
         renameSync(staging, directory);
         staging = undefined;
-        console.log(`\nReady. Start the local service:\n${process.execPath} ${JSON.stringify(start)}\n\nThen import this connection file in Envar:\n${join(directory, "connection.json")}\n\nKeep the service and HTTPS tunnel online. No task or payment was performed.`);
+        output(`\nReady. Start the local service:\n${process.execPath} ${JSON.stringify(start)}\n\nThen import this connection file in Envar:\n${join(directory, "connection.json")}\n\nKeep the service and HTTPS tunnel online. No task or payment was performed.`);
     }
     finally {
-        prompt.close();
+        prompt?.close();
         if (staging)
             rmSync(staging, { recursive: true, force: true });
     }

package/examples/hermes-skill-inventory.py

@@ -0,0 +1,107 @@
+"""Bounded, metadata-only local inventory. Never reads model credentials or executes Skills."""
+
+import hashlib
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+try:
+    import hermes_yaml as yaml
+except ImportError:
+    import yaml
+
+
+def inventory(home):
+    home = Path(home or os.environ.get("HERMES_HOME", "~/.hermes")).expanduser().resolve()
+    config = yaml.safe_load((home / "config.yaml").read_text()) or {}
+    roots = [home / "skills"]
+    roots.extend(
+        Path(os.path.expandvars(str(p))).expanduser().resolve()
+        for p in config.get("skills", {}).get("external_dirs", [])
+    )
+    result, seen = [], set()
+    for root in roots:
+        if not root.is_dir():
+            continue
+        for folder, directories, files in os.walk(root, followlinks=False):
+            directories[:] = sorted(
+                d
+                for d in directories
+                if not d.startswith(".") and not (Path(folder) / d).is_symlink()
+            )
+            if len(Path(folder).relative_to(root).parts) > 10:
+                directories[:] = []
+                continue
+            if "SKILL.md" not in files:
+                continue
+            entry = Path(folder) / "SKILL.md"
+            if entry.is_symlink() or entry.stat().st_size > 48000:
+                continue
+            raw = entry.read_text()
+            front = raw.split("---", 2)
+            try:
+                meta = (
+                    yaml.safe_load(front[1]) if raw.startswith("---\n") and len(front) == 3 else {}
+                )
+            except Exception:
+                continue
+            name = (meta or {}).get("name")
+            if (
+                not isinstance(name, str)
+                or not re.fullmatch(r"[a-z][a-z0-9-]{0,63}", name)
+                or name in seen
+            ):
+                continue
+            seen.add(name)
+            package, size, supported = [], 0, True
+            for subfolder, dirs, names in os.walk(entry.parent, followlinks=False):
+                for d in dirs[:]:
+                    if (Path(subfolder) / d).is_symlink():
+                        supported = False
+                        dirs.remove(d)
+                if len(Path(subfolder).relative_to(entry.parent).parts) > 10:
+                    supported = False
+                    dirs[:] = []
+                for file_name in sorted(names):
+                    file = Path(subfolder) / file_name
+                    if file.is_symlink() or not file.is_file() or file.stat().st_size > 512 * 1024:
+                        supported = False
+                        continue
+                    size += file.stat().st_size
+                    if size > 1024 * 1024 or len(package) >= 128:
+                        supported = False
+                        break
+                    if file.suffix.lower() not in {".md", ".txt"} and file.name != "LICENSE":
+                        supported = False
+                    package.append(
+                        [
+                            str(file.relative_to(entry.parent)),
+                            hashlib.sha256(file.read_bytes()).hexdigest(),
+                        ]
+                    )
+            digest = hashlib.sha256(
+                json.dumps(sorted(package), separators=(",", ":")).encode()
+            ).hexdigest()
+            result.append(
+                {
+                    "name": name,
+                    "digest": digest,
+                    "path": str(entry.parent),
+                    "description": str((meta or {}).get("description", ""))[:500],
+                    "supported": supported,
+                }
+            )
+            directories[:] = []
+            if len(result) >= 128:
+                return result
+    return result
+
+
+if __name__ == "__main__":
+    try:
+        print(json.dumps(inventory(sys.argv[1] if len(sys.argv) > 1 else None)))
+    except Exception:
+        print("Skill inventory unavailable", file=sys.stderr)
+        sys.exit(1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envarai/envarpay",
-  "version": "0.2.0-alpha.10",
+  "version": "0.2.0-alpha.12",
   "description": "Independent A2A service commerce, budgeted buyers and x402/MPP payments",
   "type": "module",
   "license": "MIT",