@envarai/envarpay 0.2.0-alpha.10 → 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';
@@ -22,6 +22,8 @@ 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' },
@@ -29,7 +31,7 @@ const { values, positionals } = parseArgs({ allowPositionals: true, options: {
         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 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 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 +91,14 @@ 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');
@@ -218,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() });
@@ -248,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')) {
@@ -265,6 +279,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 +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/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.js

@@ -136,18 +136,17 @@ export async function setupHermes(options) {
         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)"))
+        console.log('Newly installed Skills will be discovered privately. Enable each one from the Envar service page after reviewing text-only compatibility.');
+        const selected = (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")
+        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"));
         if (!Number.isInteger(port) || port < 1024 || port > 65535)
@@ -271,6 +270,7 @@ export async function setupHermes(options) {
             upstreams: {},
             skills: {
                 framework: "hermes",
+                discovery: { hermesHome: probe.home, enabledFromWeb: true },
                 skillsDirectory: join(directory, "skills"),
                 freeSkills: [],
                 stateDirectory,

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.11",
   "description": "Independent A2A service commerce, budgeted buyers and x402/MPP payments",
   "type": "module",
   "license": "MIT",