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

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

@@ -14,5 +14,6 @@ export declare function agentSetup(options: {
     origin?: string;
     port?: number;
     checkOnly?: boolean;
+    framework?: "hermes" | "openclaw";
 }): Promise<void>;
 export {};

package/dist/commerce/agent-setup.js

@@ -4,7 +4,8 @@ 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 { activateManagedProfile, managedProfile } from './managed.js';
+import { setupAgent, parseSetupBundle } from './setup.js';
 import { CommerceError } from './types.js';
 function privateJson(file) {
     const s = lstatSync(file);
@@ -98,7 +99,20 @@ function privateLog(file) { const s = lstatSync(file); if (!s.isFile() || s.isSy
     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 managedRoot = process.env.ENVARPAY_MANAGED_ROOT ? resolve(process.env.ENVARPAY_MANAGED_ROOT) : undefined;
+    const managedDirectory = managedRoot ? join(managedRoot, 'profiles', invite.agentId) : undefined;
+    const profile = resolve(options.directory ?? managedDirectory ?? join(homedir(), '.envarpay', invite.agentId));
+    if (managedRoot) {
+        if (options.container || profile !== managedDirectory)
+            throw new CommerceError('managed_profile', 'Use this managed runtime and its existing profile location');
+        const active = managedProfile(managedRoot);
+        if (active !== managedRoot && active !== profile)
+            throw new CommerceError('managed_bound', 'This runtime belongs to another Agent; preserve its original profile');
+        const origin = process.env.ENVARPAY_ORIGIN, port = Number(process.env.ENVARPAY_PORT ?? '4020');
+        if (!origin || new URL(origin).protocol !== 'https:' || new URL(origin).origin !== origin || !Number.isInteger(port) || port < 1024 || port > 65535 || (options.origin && options.origin !== origin) || (options.port && options.port !== port))
+            throw new CommerceError('managed_origin', 'Use the managed HTTPS origin and port');
+        options = { ...options, origin, port };
+    }
     const root = profile + '.onboarding';
     if (options.checkOnly) {
         const result = await request(invite, 'status', {});
@@ -130,7 +144,7 @@ export async function agentSetup(options) {
             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 });
+        await setupAgent({ framework: options.framework, managed: !!managedRoot, 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.');
@@ -144,26 +158,33 @@ export async function agentSetup(options) {
     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;
+    if (managedRoot) {
+        if (readFileSync(join(profile, 'envar.token'), 'utf8') !== bundle.token)
+            writeFileSync(join(profile, 'envar.token'), bundle.token, { mode: 0o600 });
+        activateManagedProfile(managedRoot, invite.agentId, profile);
+    }
+    else {
+        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 });
         }
-        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++) {
@@ -181,7 +202,7 @@ export async function agentSetup(options) {
     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 };
+    const output = { ...result, local_directory: profile, receipt_file: join(root, 'receipt.json'), scope: 'connected; not published; no payment', restart: managedRoot ? 'managed by the deployment' : `node ${JSON.stringify(join(profile, 'start.mjs'))}`, temporary_tunnel: !options.origin, automatic_restart: !!managedRoot };
     if (existsSync(join(root, 'receipt.json')))
         privateJson(join(root, 'receipt.json'));
     writeFileSync(join(root, 'receipt.json'), JSON.stringify(output, null, 2) + '\n', { mode: 0o600 });

package/dist/commerce/chain.d.ts

@@ -14,7 +14,7 @@ export interface ExpiredUnusedProof {
     authorizationUsed: false;
 }
 /** Checks the canonical chain receipt and exact official-token Transfer. */
-export declare function evmReceiptVerifier(rpcUrls: Readonly<Record<string, string>>, confirmations?: number): (receipt: SettleResponse, payload: PaymentPayload, requirements: PaymentRequirements) => Promise<boolean>;
+export declare function evmReceiptVerifier(rpcUrls: Readonly<Record<string, string>>, confirmations?: number, confirmationWaitMs?: number): (receipt: SettleResponse, payload: PaymentPayload, requirements: PaymentRequirements) => Promise<boolean>;
 /** Locate an original EIP-3009 settlement even when facilitator lost its tx response. */
 export declare function evmSettlementRecovery(rpcUrls: Readonly<Record<string, string>>): {
     expiredUnusedProof: (payload: PaymentPayload, requirements: PaymentRequirements) => Promise<ExpiredUnusedProof | undefined>;

package/dist/commerce/chain.js

@@ -1,4 +1,4 @@
-import { createPublicClient, http, decodeEventLog, parseAbi } from 'viem';
+import { createPublicClient, http, decodeEventLog, parseAbi, TransactionReceiptNotFoundError } from 'viem';
 import { CommerceError } from './types.js';
 import { validateUrl } from './config.js';
 const abi = parseAbi(['event Transfer(address indexed from, address indexed to, uint256 value)']);
@@ -9,9 +9,11 @@ const officialUsdc = {
     'eip155:8453': '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',
 };
 /** Checks the canonical chain receipt and exact official-token Transfer. */
-export function evmReceiptVerifier(rpcUrls, confirmations = 2) {
+export function evmReceiptVerifier(rpcUrls, confirmations = 2, confirmationWaitMs = 12000) {
     if (!Number.isInteger(confirmations) || confirmations < 1)
         throw new CommerceError('confirmation_policy', 'Positive confirmation depth required');
+    if (!Number.isInteger(confirmationWaitMs) || confirmationWaitMs < 0 || confirmationWaitMs > 30000)
+        throw new CommerceError('confirmation_policy', 'Confirmation wait must be between 0 and 30000 milliseconds');
     return async (receipt, payload, requirements) => {
         const rpc = rpcUrls[requirements.network];
         if (!rpc)
@@ -23,15 +25,38 @@ export function evmReceiptVerifier(rpcUrls, confirmations = 2) {
         const client = createPublicClient({ transport: http(rpc, { timeout: 15000, retryCount: 0 }) });
         if (await client.getChainId() !== chainId)
             return false;
-        const mined = await client.getTransactionReceipt({ hash: receipt.transaction });
-        if (mined.status !== 'success')
-            return false;
-        const block = await client.getBlock({ blockNumber: mined.blockNumber });
-        if (block.hash !== mined.blockHash)
-            return false;
-        const latest = await client.getBlockNumber();
-        if (latest - mined.blockNumber + 1n < BigInt(confirmations))
-            return false;
+        const deadline = Date.now() + confirmationWaitMs;
+        const wait = async () => {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return false;
+            await new Promise(resolve => setTimeout(resolve, Math.min(1000, remaining)));
+            return Date.now() < deadline;
+        };
+        let mined;
+        for (;;) {
+            try {
+                mined = await client.getTransactionReceipt({ hash: receipt.transaction });
+            }
+            catch (error) {
+                if (error instanceof TransactionReceiptNotFoundError) {
+                    if (await wait())
+                        continue;
+                    return false;
+                }
+                throw error;
+            }
+            if (mined.status !== 'success' || mined.transactionHash.toLowerCase() !== receipt.transaction.toLowerCase())
+                return false;
+            const block = await client.getBlock({ blockNumber: mined.blockNumber });
+            if (block.hash !== mined.blockHash)
+                return false;
+            const latest = await client.getBlockNumber({ cacheTime: 0 });
+            if (latest - mined.blockNumber + 1n >= BigInt(confirmations))
+                break;
+            if (!await wait())
+                return false;
+        }
         const auth = payload.payload.authorization;
         if (!auth?.from || !auth.nonce || auth.to?.toLowerCase() !== requirements.payTo.toLowerCase() || auth.value !== requirements.amount)
             return false;
@@ -131,8 +156,9 @@ export function evmSettlementRecovery(rpcUrls) {
             // RPC lookup; never reinterpret incomplete search as proof of non-payment.
             if (latest - BigInt(fromBlock) > 100000n)
                 throw new CommerceError('archive_reconciliation_required', 'Original authorization requires an archive log lookup');
-            for (let start = BigInt(fromBlock); start <= latest; start += 2000n) {
-                const end = start + 1999n < latest ? start + 1999n : latest;
+            // The default public Base RPCs limit eth_getLogs to 200-block ranges.
+            for (let start = BigInt(fromBlock); start <= latest; start += 200n) {
+                const end = start + 199n < latest ? start + 199n : latest;
                 const logs = await client.getLogs({ address: requirements.asset, event: authorizationAbi[0], args: { authorizer: auth.from, nonce: auth.nonce }, fromBlock: start, toBlock: end, strict: true });
                 const settled = logs.filter(log => !log.removed && log.transactionHash);
                 if (settled.length > 1)

package/dist/commerce/cli.js

@@ -21,7 +21,8 @@ import { evmReceiptVerifier, evmSettlementRecovery } from './chain.js';
 import { CommerceError } from './types.js';
 import { createNativeSkillExecutor } from './native-skills.js';
 import { inspectLedger, inspectLocalAlerts } from './operations.js';
-import { setupHermes } from './setup.js';
+import { serveManaged } from './managed.js';
+import { setupAgent } from './setup.js';
 import { SkillDiscovery } from './discovery.js';
 import { upgradeDiscovery, configurePayments } from './configure.js';
 import { agentSetup } from './agent-setup.js';
@@ -30,9 +31,9 @@ const { values, positionals } = parseArgs({ allowPositionals: true, options: {
         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' }, check: { type: 'boolean' },
+        framework: { type: 'string' }, file: { type: 'string' }, 'docker-container': { type: 'string' }, python: { type: 'string' }, 'hermes-home': { type: 'string' }, check: { type: 'boolean' },
     } });
-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 usage = 'envarpay onboard --file invitation.json [--framework hermes|openclaw] [--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);
@@ -92,10 +93,18 @@ async function run() {
         return;
     }
     const command = positionals[0];
+    if (values.framework && !['hermes', 'openclaw'].includes(values.framework))
+        throw new CommerceError('setup_runtime', 'Use hermes or openclaw');
+    if (command === 'managed-serve') {
+        if (!values.directory || !values.origin)
+            throw new CommerceError('managed_configuration', 'Managed serve requires its directory and HTTPS origin');
+        await serveManaged(values.directory, values.origin, values.host ?? '127.0.0.1', port(4020));
+        return;
+    }
     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 });
+        await agentSetup({ framework: values.framework, 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) {
@@ -109,7 +118,7 @@ async function run() {
     if (command === 'setup') {
         if (!values.file)
             throw new CommerceError('setup_file', 'Download the setup file from your Agent service page and pass --file PATH');
-        await setupHermes({ file: values.file, directory: values.directory, container: values['docker-container'], python: values.python, home: values['hermes-home'] });
+        await setupAgent({ framework: values.framework, file: values.file, directory: values.directory, container: values['docker-container'], python: values.python, home: values['hermes-home'] });
         return;
     }
     if (values.alerts || values['fail-on-alert'] || values['integration-state'] || values['no-integration']) {

package/dist/commerce/discovery.d.ts

@@ -3,6 +3,7 @@ import type { EnvarIntegration } from "./envar.js";
 export interface DiscoverySettings {
     hermesHome: string;
     enabledFromWeb: true;
+    roots?: string[];
 }
 export declare class SkillDiscovery {
     private settings;

package/dist/commerce/discovery.js

@@ -1,3 +1,4 @@
+import { readSkillInventory } from "./native-inventory.js";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { readFileSync, writeFileSync, existsSync, mkdtempSync, mkdirSync, renameSync, rmSync, readdirSync, lstatSync, } from "node:fs";
@@ -50,6 +51,8 @@ export class SkillDiscovery {
             : {};
     }
     async scan() {
+        if (this.discovery.roots && !this.settings.dockerContainer)
+            return readSkillInventory(this.discovery.roots);
         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

package/dist/commerce/managed.d.ts

@@ -0,0 +1,3 @@
+export declare function managedProfile(root: string): string;
+export declare function activateManagedProfile(root: string, agentId: string, profile: string): void;
+export declare function serveManaged(root: string, origin: string, host: string, port: number): Promise<void>;

package/dist/commerce/managed.js

@@ -0,0 +1,143 @@
+/** A persistent native-runtime host for the existing seller CLI. No wallet authority is added. */
+import { chownSync, closeSync, existsSync, fsyncSync, linkSync, lstatSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { DatabaseSync } from 'node:sqlite';
+import { CommerceError } from './types.js';
+const idPattern = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/;
+function rootDirectory(root) {
+    const path = resolve(root), stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077))
+        throw new CommerceError('managed_directory', 'Use the existing private managed EnvarPay directory');
+    return path;
+}
+export function managedProfile(root) {
+    const base = rootDirectory(root), file = join(base, 'active-profile.json');
+    const profiles = join(base, 'profiles');
+    if (existsSync(profiles)) {
+        const stat = lstatSync(profiles);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077))
+            throw new CommerceError('managed_profile', 'Use a private profile directory without links');
+    }
+    if (!existsSync(file))
+        return base;
+    const stat = lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 || (stat.mode & 0o077))
+        throw new CommerceError('managed_profile', 'Invalid managed profile');
+    const value = JSON.parse(readFileSync(file, 'utf8'));
+    if (value.version !== 1 || !idPattern.test(value.agentId))
+        throw new CommerceError('managed_profile', 'Invalid managed Agent identity');
+    const path = join(base, 'profiles', value.agentId), p = lstatSync(path);
+    if (!p.isDirectory() || p.isSymbolicLink() || (p.mode & 0o077))
+        throw new CommerceError('managed_profile', 'Use the original private profile');
+    return path;
+}
+export function activateManagedProfile(root, agentId, profile) {
+    const base = rootDirectory(root);
+    if (!idPattern.test(agentId) || resolve(profile) !== join(base, 'profiles', agentId))
+        throw new CommerceError('managed_profile', 'Profile does not belong to this managed Agent');
+    const previous = managedProfile(base);
+    if (previous !== base && previous !== resolve(profile))
+        throw new CommerceError('managed_bound', 'This runtime is already bound to another Agent; preserve its ledger');
+    if (previous === base) {
+        const config = JSON.parse(readFileSync(join(base, 'seller.json'), 'utf8'));
+        if (config.services?.length || Object.keys(config.paymentProfiles ?? {}).length)
+            throw new CommerceError('managed_in_use', 'Existing seller configuration requires review');
+        const ledger = join(base, 'seller.sqlite3');
+        if (existsSync(ledger)) {
+            const db = new DatabaseSync(ledger, { readOnly: true });
+            try {
+                for (const table of ['commerce_orders', 'commerce_service_revisions']) {
+                    if (db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(table) && Number(db.prepare(`SELECT count(*) AS n FROM ${table}`).get()?.n))
+                        throw new CommerceError('managed_in_use', 'Keep the existing seller ledger and inspect its operations before connecting');
+                }
+            }
+            finally {
+                db.close();
+            }
+        }
+    }
+    const owner = lstatSync(base);
+    function ownership(path) {
+        const s = lstatSync(path);
+        if (s.isSymbolicLink() || (!s.isDirectory() && !s.isFile()))
+            throw new CommerceError('managed_profile', 'Managed profiles cannot contain links or special files');
+        if (process.getuid?.() === 0)
+            chownSync(path, owner.uid, owner.gid);
+        if (s.isDirectory())
+            for (const name of readdirSync(path))
+                ownership(join(path, name));
+    }
+    ownership(join(base, 'profiles'));
+    const connection = JSON.parse(readFileSync(join(profile, 'connection.json'), 'utf8'));
+    if (connection.agentId !== agentId)
+        throw new CommerceError('managed_profile', 'Connection belongs to another Agent');
+    if (previous === resolve(profile))
+        return;
+    const temp = join(base, `.active-${process.pid}.json`);
+    writeFileSync(temp, JSON.stringify({ version: 1, agentId }), { mode: 0o600, flag: 'wx', flush: true });
+    if (process.getuid?.() === 0)
+        chownSync(temp, owner.uid, owner.gid);
+    try {
+        // Atomic create prevents two setup processes from replacing one another's binding.
+        linkSync(temp, join(base, 'active-profile.json'));
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST' || managedProfile(base) !== resolve(profile))
+            throw new CommerceError('managed_bound', 'This runtime was bound by another setup; preserve its original profile');
+    }
+    finally {
+        unlinkSync(temp);
+    }
+    const directory = openSync(base, 'r');
+    try {
+        fsyncSync(directory);
+    }
+    finally {
+        closeSync(directory);
+    }
+}
+export async function serveManaged(root, origin, host, port) {
+    const base = rootDirectory(root), cli = fileURLToPath(new URL('./cli.js', import.meta.url));
+    let child, stopping = false;
+    const stop = () => { stopping = true; child?.kill('SIGTERM'); };
+    process.once('SIGTERM', stop);
+    process.once('SIGINT', stop);
+    try {
+        while (!stopping) {
+            const profile = managedProfile(base);
+            const stamp = () => ['credentials.json', 'envar.json', 'envar.token'].map(name => { const p = join(profile, name); return existsSync(p) ? lstatSync(p).mtimeMs : 0; }).join(':');
+            const initialStamp = stamp();
+            const args = [cli, 'serve', '--config', join(profile, 'seller.json'), '--credentials', join(profile, 'credentials.json'), '--state', join(profile, 'seller.sqlite3'), '--origin', origin, '--host', host, '--port', String(port)];
+            if (profile !== base)
+                args.push('--envar-config', join(profile, 'envar.json'), '--envar-credentials', join(profile, 'envar.token'));
+            child = spawn(process.execPath, args, { stdio: 'inherit' });
+            let switching = false;
+            const timer = setInterval(() => {
+                try {
+                    if (!switching && (managedProfile(base) !== profile || stamp() !== initialStamp)) {
+                        switching = true;
+                        child?.kill('SIGTERM');
+                    }
+                }
+                catch {
+                    stop();
+                }
+            }, 1000);
+            try {
+                const [code] = await once(child, 'exit');
+                if (!stopping && !switching)
+                    throw new CommerceError('managed_runtime_exit', `Seller stopped (${code}); keep its profile and inspect its configuration`);
+            }
+            finally {
+                clearInterval(timer);
+            }
+        }
+    }
+    finally {
+        process.removeListener('SIGTERM', stop);
+        process.removeListener('SIGINT', stop);
+    }
+}

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

@@ -0,0 +1,8 @@
+export declare function readSkillInventory(roots: string[]): {
+    name: string;
+    path: string;
+    description: string;
+    supported: boolean;
+    digest: string;
+    files: number;
+}[];

package/dist/commerce/native-inventory.js

@@ -0,0 +1,72 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { extname, join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { parse } from 'yaml';
+const namePattern = /^[a-z][a-z0-9-]{0,63}$/;
+export function readSkillInventory(roots) {
+    const found = [];
+    const seen = new Set();
+    function visit(folder, depth) {
+        if (depth > 10 || found.length >= 128 || !existsSync(folder))
+            return;
+        const stat = lstatSync(folder);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return;
+        const entry = join(folder, 'SKILL.md');
+        if (!existsSync(entry)) {
+            for (const child of readdirSync(folder).sort())
+                if (!child.startsWith('.'))
+                    visit(join(folder, child), depth + 1);
+            return;
+        }
+        const info = lstatSync(entry);
+        if (!info.isFile() || info.isSymbolicLink() || info.size > 48000)
+            return;
+        const raw = readFileSync(entry, 'utf8'), header = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw)?.[1];
+        let meta;
+        try {
+            meta = parse(header ?? '') ?? {};
+        }
+        catch {
+            return;
+        }
+        if (typeof meta.name !== 'string' || !namePattern.test(meta.name) || seen.has(meta.name))
+            return;
+        const files = [];
+        let size = 0, supported = true;
+        function collect(path, prefix = '', level = 0) {
+            if (level > 10) {
+                supported = false;
+                return;
+            }
+            for (const name of readdirSync(path).sort()) {
+                const file = join(path, name), s = lstatSync(file);
+                if (s.isSymbolicLink()) {
+                    supported = false;
+                    continue;
+                }
+                if (s.isDirectory()) {
+                    collect(file, prefix + name + '/', level + 1);
+                    continue;
+                }
+                if (!s.isFile() || s.size > 512 * 1024 || (size += s.size) > 1024 * 1024 || files.length >= 128) {
+                    supported = false;
+                    continue;
+                }
+                if (!['.md', '.txt'].includes(extname(name).toLowerCase()) && name !== 'LICENSE')
+                    supported = false;
+                files.push([prefix + name, createHash('sha256').update(readFileSync(file)).digest('hex')]);
+            }
+        }
+        collect(folder);
+        files.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+        const canonical = JSON.stringify(files).replace(/[\u007f-\uffff]/g, c => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));
+        seen.add(meta.name);
+        found.push({ name: meta.name, path: resolve(folder), description: String(meta.description ?? '').slice(0, 500), supported, digest: createHash('sha256').update(canonical).digest('hex'), files: files.length });
+    }
+    for (const root of roots.slice(0, 16))
+        if (typeof root === 'string')
+            visit(resolve(root.replace(/^~(?=\/|$)/, homedir())), 0);
+    return found;
+}

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

@@ -16,6 +16,7 @@ export interface NativeSkillSettings {
     discovery?: {
         hermesHome: string;
         enabledFromWeb: true;
+        roots?: string[];
     };
 }
 interface InstalledSkill {

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

@@ -0,0 +1,28 @@
+export declare function openclawRoots(home?: string): string[];
+export declare function openclawInventory(home?: string): {
+    name: string;
+    path: string;
+    description: string;
+    supported: boolean;
+    digest: string;
+    files: number;
+}[];
+export declare function probeOpenClaw(home?: string, python?: string): {
+    home: string;
+    python: string;
+    command: string[];
+    model: string;
+    baseUrl: any;
+    apiKeyFile: null;
+    apiKey: string;
+    skillRoots: string[];
+    skills: {
+        textPackage: boolean;
+        name: string;
+        path: string;
+        description: string;
+        supported: boolean;
+        digest: string;
+        files: number;
+    }[];
+};

package/dist/commerce/openclaw-setup.js

@@ -0,0 +1,43 @@
+/** Read local OpenClaw configuration and installed Skill metadata without invoking a model. */
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { readSkillInventory } from './native-inventory.js';
+import { CommerceError } from './types.js';
+function configuration(home) {
+    const path = home ? join(resolve(home), 'openclaw.json') : process.env.OPENCLAW_CONFIG_PATH ?? join(process.env.OPENCLAW_STATE_DIR ?? join(homedir(), '.openclaw'), 'openclaw.json');
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+        throw new CommerceError('setup_model', 'Use a bounded local OpenClaw configuration file');
+    return { home: dirname(resolve(path)), config: JSON.parse(readFileSync(path, 'utf8')) };
+}
+export function openclawRoots(home) {
+    const local = configuration(home), config = local.config, defaults = config.agents?.defaults ?? {};
+    const agent = config.agents?.list?.find((a) => a.default || a.id === 'main');
+    return [join(local.home, 'skills'), join(agent?.workspace ?? defaults.workspace ?? join(local.home, 'workspace'), 'skills'), ...(config.skills?.load?.extraDirs ?? [])].filter((r) => typeof r === 'string');
+}
+export function openclawInventory(home) { return readSkillInventory(openclawRoots(home)); }
+export function probeOpenClaw(home, python = 'python3') {
+    const local = configuration(home), config = local.config;
+    const agent = config.agents?.list?.find((a) => a.default || a.id === 'main');
+    const selected = agent?.model ?? config.agents?.defaults?.model;
+    const primary = typeof selected === 'string' ? selected : selected?.primary;
+    if (typeof primary !== 'string' || !primary.includes('/'))
+        throw new CommerceError('setup_model', 'Configure an OpenAI-compatible OpenClaw model first');
+    const slash = primary.indexOf('/'), provider = config.models?.providers?.[primary.slice(0, slash)], model = primary.slice(slash + 1);
+    let key = provider?.apiKey;
+    if (typeof key === 'string') {
+        const env = /^\$\{([A-Z_][A-Z0-9_]*)\}$/.exec(key);
+        if (env)
+            key = process.env[env[1]];
+    }
+    else if (key?.source === 'env' && typeof key.id === 'string')
+        key = process.env[key.id];
+    if (typeof key !== 'string' || !key.trim() || typeof provider?.baseUrl !== 'string' || (provider.api ?? 'openai-completions') !== 'openai-completions')
+        throw new CommerceError('setup_model', 'Use an OpenAI-compatible provider with a locally available API key');
+    const command = existsSync('/app/openclaw.mjs') ? [process.execPath, '/app/openclaw.mjs'] : ['openclaw'];
+    execFileSync(python, ['--version'], { stdio: 'pipe', timeout: 10000 });
+    execFileSync(command[0], [...command.slice(1), '--version'], { stdio: 'pipe', timeout: 30000 });
+    return { home: local.home, python, command, model, baseUrl: provider.baseUrl, apiKeyFile: null, apiKey: key, skillRoots: openclawRoots(local.home), skills: openclawInventory(local.home).map(s => ({ ...s, textPackage: s.supported })) };
+}

package/dist/commerce/setup.d.ts

@@ -9,7 +9,9 @@ export interface SetupBundle {
 }
 export declare function parseSetupBundle(raw: unknown): SetupBundle;
 export declare function prepareTextSkill(source: string, destination: string, name: string): void;
-export declare function setupHermes(options: {
+export declare function setupAgent(options: {
+    framework?: "hermes" | "openclaw";
+    managed?: boolean;
     file: string;
     directory?: string;
     container?: string;
@@ -20,3 +22,4 @@ export declare function setupHermes(options: {
         origin: string;
     };
 }): Promise<void>;
+export declare const setupHermes: (options: Parameters<typeof setupAgent>[0]) => Promise<void>;

package/dist/commerce/setup.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline/promises";
+import { probeOpenClaw } from "./openclaw-setup.js";
 import { readInstalledSkills } from "./native-skills.js";
 import { loadCommerceConfig, validateUrl } from "./config.js";
 import { CommerceError } from "./types.js";
@@ -62,7 +63,7 @@ function privateJson(path, value) {
         flag: "wx",
     });
 }
-export async function setupHermes(options) {
+export async function setupAgent(options) {
     const file = resolve(options.file), info = lstatSync(file);
     if (!info.isFile() || info.isSymbolicLink() || info.size > 16384)
         throw new CommerceError("setup_file", "Use the downloaded setup JSON file");
@@ -83,65 +84,75 @@ export async function setupHermes(options) {
         const directory = resolve(options.directory ?? join(homedir(), ".envarpay", bundle.agentId));
         if (existsSync(directory))
             throw new CommerceError("setup_exists", "This Agent already has a local directory. Use its start script; never reset its ledger.");
+        const configuredFramework = process.env.ENVARPAY_FRAMEWORK;
+        const framework = options.framework ?? (configuredFramework === "hermes" || configuredFramework === "openclaw" ? configuredFramework : process.env.OPENCLAW_STATE_DIR ? "openclaw" : "hermes");
         let python = options.python;
-        const compatibility = 'import inspect;from run_agent import AIAgent;assert all(k in inspect.signature(AIAgent).parameters for k in ["skip_context_files","skip_memory","skip_background_review","ephemeral_system_prompt","enabled_toolsets"])';
-        if (!python && options.container) {
-            for (const candidate of [
-                "/opt/hermes-latest/bin/python",
-                "/opt/hermes/.venv/bin/python",
-                "python3",
-            ]) {
-                try {
-                    execFileSync("docker", ["exec", options.container, candidate, "-c", compatibility], { stdio: "pipe", timeout: 60000 });
-                    python = candidate;
-                    break;
-                }
-                catch {
-                    /* try the next compatible installed interpreter */
+        let probe;
+        if (framework === "openclaw") {
+            if (options.container)
+                throw new CommerceError("setup_runtime", "Run OpenClaw setup inside its own runtime");
+            python ??= "python3";
+            probe = probeOpenClaw(options.home, python);
+        }
+        else {
+            const compatibility = 'import inspect;from run_agent import AIAgent;assert all(k in inspect.signature(AIAgent).parameters for k in ["skip_context_files","skip_memory","skip_background_review","ephemeral_system_prompt","enabled_toolsets"])';
+            if (!python && options.container) {
+                for (const candidate of [
+                    "/opt/hermes-latest/bin/python",
+                    "/opt/hermes/.venv/bin/python",
+                    "python3",
+                ]) {
+                    try {
+                        execFileSync("docker", ["exec", options.container, candidate, "-c", compatibility], { stdio: "pipe", timeout: 60000 });
+                        python = candidate;
+                        break;
+                    }
+                    catch {
+                        /* try the next compatible installed interpreter */
+                    }
                 }
+                if (!python)
+                    throw new CommerceError("setup_runtime", "No compatible Hermes interpreter found in this container. Update Hermes or pass --python PATH.");
             }
-            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;
+            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 { }
                 }
-                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");
+            try {
+                if (options.container)
+                    execFileSync("docker", ["exec", options.container, python, "-c", compatibility], { stdio: "pipe", timeout: 60000 });
+                else
+                    execFileSync(python, ["-c", compatibility], {
+                        stdio: "pipe",
+                        timeout: 60000,
+                    });
+                const args = ["-c", probeSource, ...(options.home ? [options.home] : [])];
+                const data = options.container
+                    ? execFileSync("docker", ["exec", options.container, python, ...args], {
+                        stdio: "pipe",
+                        timeout: 30000,
+                        maxBuffer: 2 * 1024 * 1024,
+                    })
+                    : execFileSync(python, args, {
+                        stdio: "pipe",
+                        timeout: 30000,
+                        maxBuffer: 2 * 1024 * 1024,
+                    });
+                probe = JSON.parse(data.toString());
+            }
+            catch {
+                throw new CommerceError("setup_model", "Could not read Hermes. Check the container/Python path and configure an OpenAI-compatible model in Hermes first.");
             }
-            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;
-        try {
-            if (options.container)
-                execFileSync("docker", ["exec", options.container, python, "-c", compatibility], { stdio: "pipe", timeout: 60000 });
-            else
-                execFileSync(python, ["-c", compatibility], {
-                    stdio: "pipe",
-                    timeout: 60000,
-                });
-            const args = ["-c", probeSource, ...(options.home ? [options.home] : [])];
-            const data = options.container
-                ? execFileSync("docker", ["exec", options.container, python, ...args], {
-                    stdio: "pipe",
-                    timeout: 30000,
-                    maxBuffer: 2 * 1024 * 1024,
-                })
-                : execFileSync(python, args, {
-                    stdio: "pipe",
-                    timeout: 30000,
-                    maxBuffer: 2 * 1024 * 1024,
-                });
-            probe = JSON.parse(data.toString());
-        }
-        catch {
-            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));
         output(`Model: ${probe.model}\nInstalled text packages (review their instructions before selecting):`);
@@ -154,7 +165,7 @@ export async function setupHermes(options) {
             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");
-        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.");
+        output("This adapter supplies buyer text and bundled Markdown references. Browser, script, file and API tools are disabled. Original Agent 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;
@@ -231,6 +242,13 @@ export async function setupHermes(options) {
         readInstalledSkills(skillsDirectory, [], origin + "/.well-known/agent-card.json");
         const access = randomBytes(36).toString("base64url");
         let apiKeyFile = probe.apiKeyFile;
+        if (options.managed && apiKeyFile) {
+            const stat = lstatSync(apiKeyFile);
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16384)
+                throw new CommerceError("setup_model", "Invalid local model key file");
+            probe.apiKey = readFileSync(apiKeyFile, "utf8");
+            apiKeyFile = null;
+        }
         if (!apiKeyFile) {
             if (options.container) {
                 apiKeyFile = join(probe.home, "envarpay-secrets", bundle.agentId, "model.key");
@@ -279,8 +297,9 @@ export async function setupHermes(options) {
             callers: { [access]: "owner" },
             upstreams: {},
             skills: {
-                framework: "hermes",
-                discovery: { hermesHome: probe.home, enabledFromWeb: true },
+                framework,
+                ...(probe.command ? { command: probe.command } : {}),
+                discovery: { hermesHome: probe.home, enabledFromWeb: true, ...(probe.skillRoots ? { roots: probe.skillRoots } : {}) },
                 skillsDirectory: join(directory, "skills"),
                 freeSkills: [],
                 stateDirectory,
@@ -352,3 +371,5 @@ export async function setupHermes(options) {
             rmSync(staging, { recursive: true, force: true });
     }
 }
+// Preserve the existing SDK helper name for callers using Hermes explicitly.
+export const setupHermes = (options) => setupAgent({ ...options, framework: "hermes" });

package/examples/hermes-setup-probe.py

@@ -18,7 +18,8 @@ def inspect(home):
     model = config.get("model", {})
     if isinstance(model, str):
         model = {"default": model}
-    provider = config.get("providers", {}).get(model.get("provider"), {})
+    provider_id = str(model.get("provider", "")).removeprefix("custom:")
+    provider = config.get("providers", {}).get(provider_id, {})
     dotenv = {}
     if (home / ".env").exists():
         for line in (home / ".env").read_text().splitlines():
@@ -32,6 +33,8 @@ def inspect(home):
     key = (
         provider.get("api_key")
         or provider.get("key")
+        or dotenv.get(provider.get("key_env", ""))
+        or os.environ.get(provider.get("key_env", ""))
         or dotenv.get("OPENAI_API_KEY")
         or os.environ.get("OPENAI_API_KEY")
     )
@@ -90,6 +93,7 @@ def inspect(home):
         "apiKeyFile": key_file,
         "apiKey": None if key_file else key,
         "skills": skills,
+        "skillRoots": [str(root) for root in roots],
     }
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envarai/envarpay",
-  "version": "0.2.0-alpha.12",
+  "version": "0.2.0-alpha.14",
   "description": "Independent A2A service commerce, budgeted buyers and x402/MPP payments",
   "type": "module",
   "license": "MIT",
@@ -68,7 +68,8 @@
     "ajv-formats": "3.0.1",
     "canonicalize": "2.1.0",
     "mppx": "0.13.1",
-    "viem": "2.57.1"
+    "viem": "2.57.1",
+    "yaml": "2.8.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",