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

package/dist/commerce/cli.js

@@ -19,12 +19,17 @@ import { CredentialVault } from './vault.js';
 import { X402Gate } from './x402.js';
 import { evmReceiptVerifier, evmSettlementRecovery } from './chain.js';
 import { CommerceError } from './types.js';
+import { createNativeSkillExecutor } from './native-skills.js';
+import { inspectLedger, inspectLocalAlerts } from './operations.js';
+import { setupHermes } from './setup.js';
 const { values, positionals } = parseArgs({ allowPositionals: true, options: {
         config: { type: 'string' }, service: { type: 'string' }, offer: { type: 'string' }, origin: { type: 'string' },
         version: { type: 'boolean' }, help: { type: 'boolean', short: 'h' }, state: { type: 'string' }, credentials: { type: 'string' }, host: { type: 'string' },
         port: { type: 'string' }, directory: { type: 'string' }, 'envar-config': { type: 'string' }, 'envar-credentials': { type: 'string' },
+        after: { type: 'string' }, limit: { type: 'string' }, 'refund-review': { type: 'boolean' }, alerts: { type: 'boolean' }, 'fail-on-alert': { type: 'boolean' }, 'integration-state': { type: 'string' }, 'no-integration': { type: 'boolean' },
+        file: { type: 'string' }, 'docker-container': { type: 'string' }, python: { type: 'string' }, 'hermes-home': { type: 'string' },
     } });
-const usage = 'envarpay init --directory DIR | validate --config seller.json | card --config seller.json --service ID --offer ID --origin URL | serve/buyer-serve --config FILE --credentials FILE --state DB --origin URL';
+const usage = 'envarpay setup --file envar-setup.json [--docker-container NAME | --python PATH] [--hermes-home PATH] [--directory DIR]\ninit --directory DIR | inspect --state DB [--after ROW --limit 100 --refund-review] [--alerts --config buyer-policy.json --integration-state DB/--no-integration --fail-on-alert] | validate --config seller.json | card --config seller.json --service ID --offer ID --origin URL | serve/buyer-serve --config FILE --credentials FILE --state DB --origin URL';
 const closers = [];
 function privateFile(path) {
     const stat = lstatSync(path);
@@ -84,6 +89,27 @@ async function run() {
         return;
     }
     const command = positionals[0];
+    if (command === 'setup') {
+        if (!values.file)
+            throw new CommerceError('setup_file', 'Download the setup file from your Agent service page and pass --file PATH');
+        await setupHermes({ file: values.file, directory: values.directory, container: values['docker-container'], python: values.python, home: values['hermes-home'] });
+        return;
+    }
+    if (values.alerts || values['fail-on-alert'] || values['integration-state'] || values['no-integration']) {
+        if (command !== 'inspect' || !values.state || !values.alerts || values['refund-review'] || values.after || values.limit || (values['no-integration'] && values['integration-state']))
+            throw new CommerceError('inspection_view', 'Alert inspection needs inspect --state and --alerts, without pagination or refund review; choose at most one integration source');
+        const report = inspectLocalAlerts(values.state, { policyPath: values.config, integrationPath: values['integration-state'], integrationDisabled: values['no-integration'] });
+        console.log(JSON.stringify(report, null, 2));
+        if (values['fail-on-alert'])
+            process.exitCode = report.recommendedExitCode;
+        return;
+    }
+    if (command === 'inspect' && values.state) {
+        console.log(JSON.stringify(inspectLedger(values.state, Number(values.after ?? 0), Number(values.limit ?? 100), values['refund-review'] ? 'refund-review' : 'attention'), null, 2));
+        return;
+    }
+    if (values['refund-review'])
+        throw new CommerceError('inspection_view', 'Refund review is available only for inspect');
     if ((values['envar-config'] || values['envar-credentials']) && command !== 'serve')
         throw new CommerceError('envar_role', 'Configuration synchronization is available on seller serve only');
     if (Boolean(values['envar-config']) !== Boolean(values['envar-credentials']))
@@ -117,15 +143,36 @@ async function run() {
                 throw new CommerceError('buyer_key', 'Signer file must contain one 32-byte 0x-prefixed private key');
             signer = privateKeyToAccount(key);
         }
-        if (needsMpp && !secrets.mppAdapterModule)
-            throw new CommerceError('mpp_adapter_module', 'MPP peers require an explicit local adapter module for authorized funding and receipt verification');
-        const mpp = needsMpp ? await loadMppAdapter(secrets.mppAdapterModule) : undefined;
+        if (secrets.mppAdapterModule && secrets.mppStripe)
+            throw new CommerceError('mpp_configuration', 'Choose the built-in Stripe issuer or one explicit adapter module');
+        if (needsMpp && !secrets.mppAdapterModule && !secrets.mppStripe)
+            throw new CommerceError('mpp_configuration', 'MPP peers require a configured Stripe issuer or explicit authorized funding adapter');
+        const buyerVault = secrets.vaultKeyFile ? new CredentialVault(join(dirname(values.state), 'buyer-authorizations'), privateFile(secrets.vaultKeyFile)) : undefined;
+        let mpp;
+        if (needsMpp && secrets.mppStripe) {
+            const configured = secrets.mppStripe;
+            if (!configured.secretKeyFile || !configured.sellers || typeof configured.sellers !== 'object' || Array.isArray(configured.sellers))
+                throw new CommerceError('mpp_configuration', 'Stripe issuer and seller read credentials must use private key files');
+            const { createStripeMppBuyer } = await import('./stripe-issuer.js');
+            const adapter = createStripeMppBuyer({
+                payer: configured.payer, mode: configured.mode, issuerAccountId: configured.issuerAccountId,
+                secretKey: privateFile(configured.secretKeyFile).toString('utf8').trim(), paymentMethod: configured.paymentMethod,
+                ...(configured.publishableKey !== undefined ? { publishableKey: configured.publishableKey } : {}),
+                sellers: Object.fromEntries(Object.entries(configured.sellers).map(([id, seller]) => [id, { accountId: seller.accountId, secretKey: privateFile(seller.secretKeyFile).toString('utf8').trim() }])),
+                ...(configured.issuance ? { issuance: configured.issuance } : {}), ...(configured.returnUrl ? { returnUrl: configured.returnUrl } : {}),
+            }, { statePath: values.state + '.stripe-issuer.sqlite3', vault: buyerVault });
+            closers.push(() => adapter.close());
+            await adapter.assertReady();
+            mpp = adapter;
+        }
+        else if (needsMpp)
+            mpp = await loadMppAdapter(secrets.mppAdapterModule);
         const { BuyerStore } = await import('./buyer-store.js');
         const { CommerceBuyer } = await import('./buyer.js');
         const { BuyerManagement, listenBuyerManagement } = await import('./management.js');
         const store = new BuyerStore(values.state);
         closers.push(() => store.close());
-        const buyer = new CommerceBuyer({ policy, store, vault: secrets.vaultKeyFile ? new CredentialVault(join(dirname(values.state), 'buyer-authorizations'), privateFile(secrets.vaultKeyFile)) : undefined,
+        const buyer = new CommerceBuyer({ policy, store, vault: buyerVault,
             signer, mpp, peerTokens: secrets.peerTokens, peerEndpoints: secrets.peerEndpoints,
             ...(needsEvm ? { verifyReceipt: evmReceiptVerifier(secrets.rpcUrls), ...evmSettlementRecovery(secrets.rpcUrls) } : {}) });
         closers.push(() => buyer.stop());
@@ -217,7 +264,10 @@ async function run() {
         gates.mpp = gate;
         stripeRecipientFor = ref => gate.merchantRecipient(ref);
     }
-    const upstreams = new PinnedUpstreams(join(dirname(values.state), 'upstream-bindings.json'), secrets.upstreams, secrets.upstreamInputEncoding, fetch, controller.signal);
+    const nativeSkills = secrets.skills ? createNativeSkillExecutor(secrets.skills, values.origin, config.agent.name) : undefined;
+    if (nativeSkills)
+        closers.push(() => nativeSkills.close());
+    const upstreams = new PinnedUpstreams(join(dirname(values.state), 'upstream-bindings.json'), secrets.upstreams ?? {}, secrets.upstreamInputEncoding, fetch, controller.signal, nativeSkills?.execute);
     upstreams.prepare(config, store.catalogHistory().map(entry => entry.service));
     const validateAdapters = (candidate) => {
         for (const profile of Object.values(candidate.paymentProfiles)) {

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

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

package/dist/commerce/config.d.ts

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

package/dist/commerce/config.js

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

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

@@ -8,10 +8,11 @@ export declare class PinnedUpstreams {
     private readonly inputEncoding;
     private readonly fetchImpl;
     private readonly signal?;
+    private readonly skills?;
     private bindings;
     private readonly executors;
     readonly execute: ExecuteOrder;
-    constructor(path: string, credentials: Readonly<Record<string, string>>, inputEncoding?: Readonly<Record<string, "data" | "json-text">>, fetchImpl?: typeof fetch, signal?: AbortSignal | undefined);
+    constructor(path: string, credentials: Readonly<Record<string, string>>, inputEncoding?: Readonly<Record<string, "data" | "json-text">>, fetchImpl?: typeof fetch, signal?: AbortSignal | undefined, skills?: ExecuteOrder | undefined);
     prepare(config: CommerceConfig, history?: readonly Service[]): void;
     private executor;
 }

package/dist/commerce/envar-runtime.js

@@ -50,15 +50,17 @@ export class PinnedUpstreams {
     inputEncoding;
     fetchImpl;
     signal;
+    skills;
     bindings = {};
     executors = new Map();
     execute;
-    constructor(path, credentials, inputEncoding = {}, fetchImpl = fetch, signal) {
+    constructor(path, credentials, inputEncoding = {}, fetchImpl = fetch, signal, skills) {
         this.path = path;
         this.credentials = credentials;
         this.inputEncoding = inputEncoding;
         this.fetchImpl = fetchImpl;
         this.signal = signal;
+        this.skills = skills;
         if (existsSync(path)) {
             const value = privateJson(path);
             if (value.version !== 1 ||
@@ -92,10 +94,22 @@ export class PinnedUpstreams {
             }
             return undefined;
         };
+        if (skills) {
+            this.execute.assertSkill = (service) => skills.assertSkill(service);
+            this.execute.skillCard = skills.skillCard;
+        }
     }
     prepare(config, history = []) {
         const next = structuredClone(this.bindings), current = new Set(config.services.map((s) => `${s.id}:${s.revision}`));
         for (const service of [...history, ...config.services]) {
+            if (service.execution.type === 'skill') {
+                if (!this.skills)
+                    throw new CommerceError('skill_gate_required', 'Configure the native skill runtime');
+                // Retired versions stay readable even after their skill package is upgraded.
+                if (current.has(`${service.id}:${service.revision}`))
+                    this.skills.assertSkill(service);
+                continue;
+            }
             const key = `${service.id}:${service.revision}`, saved = next[key], explicit = this.credentials[key];
             if (saved) {
                 if (saved.cardUrl !== service.execution.cardUrl ||
@@ -120,6 +134,11 @@ export class PinnedUpstreams {
         this.bindings = next;
     }
     executor(service) {
+        if (service.execution.type === 'skill') {
+            if (!this.skills)
+                throw new CommerceError('skill_gate_required', 'Configure the native skill runtime');
+            return this.skills;
+        }
         const key = `${service.id}:${service.revision}`, binding = this.bindings[key];
         if (!binding || binding.cardUrl !== service.execution.cardUrl)
             throw new CommerceError("upstream_binding_missing", "Original runtime credential binding is unavailable");
@@ -147,6 +166,7 @@ export function mergeEnvarService(base, candidate) {
     const profiles = { ...base.paymentProfiles, ...incoming.paymentProfiles }, services = [...retained, service], used = new Set(services.flatMap((s) => s.offers.map((o) => o.paymentProfile).filter((p) => !!p)));
     return loadCommerceConfig({
         ...base,
+        configVersion: Math.max(base.configVersion, incoming.configVersion),
         paymentProfiles: Object.fromEntries(Object.entries(profiles).filter(([key]) => used.has(key))),
         services,
     });

package/dist/commerce/index.d.ts

@@ -2,3 +2,4 @@ export * from './types.js';
 export * from './config.js';
 export * from './pricing.js';
 export * from './card.js';
+export * from './skill-gate.js';

package/dist/commerce/index.js

@@ -2,3 +2,4 @@ export * from './types.js';
 export * from './config.js';
 export * from './pricing.js';
 export * from './card.js';
+export * from './skill-gate.js';

package/dist/commerce/management.js

@@ -77,9 +77,11 @@ export class BuyerManagement {
                     throw new CommerceError('invalid_request', 'Confirmation identifiers must be strings');
                 return Response.json(await this.options.buyer.confirm(caller, body), { headers });
             }
-            const match = /^\/management\/v1\/purchases\/([0-9a-f-]{36})(\/(?:recover|continue))?$/.exec(url.pathname);
+            const match = /^\/management\/v1\/purchases\/([0-9a-f-]{36})(\/(?:recover|continue|authentication))?$/.exec(url.pathname);
             if (match && request.method === 'GET' && !match[2])
                 return Response.json(this.options.buyer.get(caller, match[1]), { headers });
+            if (match && request.method === 'GET' && match[2] === '/authentication')
+                return Response.json(await this.options.buyer.authentication(caller, match[1]), { headers });
             if (match && request.method === 'POST' && match[2] === '/continue') {
                 const body = await jsonBody(request);
                 exactKeys(body, ['messageId', 'input']);

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

@@ -28,16 +28,27 @@ export interface MppVerificationContext {
     mode: 'test' | 'live';
     operationId: string;
 }
+export interface MppAuthenticationAction {
+    type: 'use_stripe_sdk';
+    hashedValue: string;
+    publishableKey: string;
+}
+/** Explicit official sandbox aliases, never accepted for live funding. */
+export declare const STRIPE_TEST_PAYMENT_METHODS: readonly ["pm_card_visa", "pm_card_visa_chargeDeclined", "pm_card_authenticationRequired"];
+export declare function isStripeTestPaymentMethod(value: string): boolean;
 export interface MppBuyerOptions {
     /** Stable private buyer/PSP identity; never inferred from seller metadata. */
     payer: string;
     mode: 'test' | 'live';
     paymentMethod: string;
+    issuance?: 'issued-token' | 'test-helper';
     createToken: (operation: MppTokenOperation) => Promise<string>;
     /** Read the original operation only; never create another SPT on absence. */
     recoverToken?: (operation: MppTokenOperation) => Promise<string | undefined>;
     /** Independently read provider state and match account/mode/merchant/amount/order. */
     verifyReceipt: (receipt: MppReceipt, context: MppVerificationContext) => Promise<boolean>;
+    /** Read only, for the owner of this exact original purchase. Never completes payment. */
+    getAuthentication?: (context: MppVerificationContext) => Promise<MppAuthenticationAction | undefined>;
 }
 export interface SavedMppAuthorization {
     protocol: 'mpp';

package/dist/commerce/mpp-client.js

@@ -3,6 +3,11 @@ import { Mppx } from 'mppx/client';
 import { charge } from 'mppx/stripe/client';
 import { createHash } from 'node:crypto';
 import { CommerceError } from './types.js';
+/** Explicit official sandbox aliases, never accepted for live funding. */
+export const STRIPE_TEST_PAYMENT_METHODS = ['pm_card_visa', 'pm_card_visa_chargeDeclined', 'pm_card_authenticationRequired'];
+export function isStripeTestPaymentMethod(value) {
+    return STRIPE_TEST_PAYMENT_METHODS.includes(value);
+}
 /** Native SDK preparation only; no fetch polyfill or automatic payment retry. */
 export async function prepareMppCredential(challenge, paymentMethod, createToken) {
     const client = Mppx.create({ polyfill: false, maxPaymentRetries: 0, methods: [charge({ paymentMethod, createToken })] });

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

@@ -1,3 +1,4 @@
 /** Opt-in MPP server adapter. Account eligibility is checked at startup. */
 export * from './mpp.js';
 export * from './stripe-provider.js';
+export * from './stripe-issuer.js';

package/dist/commerce/mpp-runtime.js

@@ -1,3 +1,4 @@
 /** Opt-in MPP server adapter. Account eligibility is checked at startup. */
 export * from './mpp.js';
 export * from './stripe-provider.js';
+export * from './stripe-issuer.js';

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

@@ -0,0 +1,27 @@
+import { type SkillDescriptor } from './skill-gate.js';
+import type { ExecuteOrder } from './server.js';
+export interface NativeSkillSettings {
+    framework: 'hermes' | 'openclaw';
+    skillsDirectory: string;
+    freeSkills: string[];
+    stateDirectory: string;
+    python: string;
+    command?: string[];
+    model: string;
+    baseUrl: string;
+    apiKeyFile: string;
+    /** Host-side Docker CLI, never a Docker socket mounted into the Agent. */
+    dockerContainer?: string;
+    dockerStateDirectory?: string;
+}
+interface InstalledSkill {
+    descriptor: SkillDescriptor;
+    instructions: string;
+}
+/** Hash every resource; reject symlinks, unbounded packages and executable skill requirements. */
+export declare function readInstalledSkills(root: string, freeSkills: readonly string[], cardUrl: string): InstalledSkill[];
+export declare function createNativeSkillExecutor(settings: NativeSkillSettings, origin: string, agentName: string): {
+    execute: ExecuteOrder;
+    close(): Promise<void>;
+};
+export {};

package/dist/commerce/native-skills.js

@@ -0,0 +1,176 @@
+/** Owner-operated, instruction-only skill runtime. No model file, shell or network tools. */
+import { AgentCard, Task } from '@a2a-js/sdk';
+import { createHash, randomUUID } from 'node:crypto';
+import { lstatSync, readFileSync, readdirSync, mkdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { DatabaseSync } from 'node:sqlite';
+import { digest } from './config.js';
+import { CommerceError } from './types.js';
+import { skillScopedExecutor } from './skill-gate.js';
+const namePattern = /^[a-z][a-z0-9-]{0,63}$/;
+/** Hash every resource; reject symlinks, unbounded packages and executable skill requirements. */
+export function readInstalledSkills(root, freeSkills, cardUrl) {
+    const base = resolve(root), rootStat = lstatSync(base);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new CommerceError('skill_directory', 'Use a real installed skill directory');
+    const output = [];
+    for (const entry of readdirSync(base, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.name.startsWith('.'))
+            continue;
+        if (!entry.isDirectory() || entry.isSymbolicLink() || !namePattern.test(entry.name))
+            throw new CommerceError('skill_package', 'Use one real directory per exact skill name');
+        const files = [];
+        let total = 0;
+        function walk(folder, prefix = '') {
+            if (prefix.split('/').length > 12)
+                throw new CommerceError('skill_size', 'Skill package nesting exceeds the supported limit');
+            for (const item of readdirSync(folder, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+                const path = join(folder, item.name), relative = prefix + item.name;
+                if (item.isSymbolicLink())
+                    throw new CommerceError('skill_symlink', 'Skill packages cannot contain symlinks');
+                if (item.isDirectory()) {
+                    walk(path, relative + '/');
+                    continue;
+                }
+                const stat = lstatSync(path);
+                if (!stat.isFile() || stat.size > 512 * 1024 || files.length >= 128 || (total += stat.size) > 1024 * 1024)
+                    throw new CommerceError('skill_size', 'Skill package exceeds supported size');
+                files.push({ path: relative, sha256: createHash('sha256').update(readFileSync(path)).digest('hex') });
+            }
+        }
+        walk(join(base, entry.name));
+        const instructions = readFileSync(join(base, entry.name, 'SKILL.md'), 'utf8');
+        const front = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(instructions)?.[1];
+        const name = /^name:\s*["']?([a-z][a-z0-9-]*)["']?\s*$/m.exec(front ?? '')?.[1];
+        if (name !== entry.name || instructions.length > 48000)
+            throw new CommerceError('skill_name_mismatch', 'SKILL.md name must match its installed directory');
+        // This adapter deliberately supports only text-in/text-out workflows. Owners must use
+        // a separately reviewed adapter for skills needing code, browsing, external APIs or files.
+        if (!/^envar-runtime:\s*instruction-only\s*$/m.test(front ?? ''))
+            throw new CommerceError('skill_runtime_required', 'Review and mark each compatible skill envar-runtime: instruction-only before publication');
+        const description = /^description:\s*(.+)$/m.exec(front ?? '')?.[1]?.replace(/^["']|["']$/g, '') ?? name;
+        const references = files.filter(file => file.path !== 'SKILL.md' && file.path.endsWith('.md')).map(file => `\n\n<skill-reference path="${file.path}">\n${readFileSync(join(base, entry.name, file.path), 'utf8')}\n</skill-reference>`).join('');
+        if (instructions.length + references.length > 120000)
+            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');
+    // 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 }));
+    for (const skill of output)
+        skill.descriptor.digest = digest({ package: skill.descriptor.digest, helpers });
+    return output;
+}
+export function createNativeSkillExecutor(settings, origin, agentName) {
+    if (!['hermes', 'openclaw'].includes(settings.framework) || !Array.isArray(settings.freeSkills) || !settings.python || !settings.model || !settings.baseUrl)
+        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();
+    mkdirSync(settings.stateDirectory, { recursive: true, mode: 0o700 });
+    const stateStat = lstatSync(settings.stateDirectory);
+    if (!stateStat.isDirectory() || stateStat.isSymbolicLink() || (stateStat.mode & 0o077) !== 0)
+        throw new CommerceError('skill_state', 'Skill state must be owner-only');
+    const db = new DatabaseSync(join(settings.stateDirectory, 'skills.sqlite3'));
+    db.exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; CREATE TABLE IF NOT EXISTS skill_tasks (id TEXT PRIMARY KEY, order_id TEXT UNIQUE NOT NULL, binding TEXT NOT NULL, task_json TEXT NOT NULL)');
+    for (const row of db.prepare('SELECT id,task_json FROM skill_tasks').all()) {
+        const task = JSON.parse(String(row.task_json));
+        if (task.status?.state === 'TASK_STATE_WORKING') {
+            task.status = { state: 'TASK_STATE_FAILED', message: { role: 'ROLE_AGENT', messageId: randomUUID(), parts: [{ text: 'Native execution interrupted; inspect this original order' }] } };
+            db.prepare('UPDATE skill_tasks SET task_json=? WHERE id=?').run(JSON.stringify(task), row.id);
+        }
+    }
+    const inFlight = new Map();
+    const runner = fileURLToPath(new URL('../../examples/native-skill-runner.py', import.meta.url));
+    function readTask(id, invocation) {
+        const row = db.prepare('SELECT order_id,task_json FROM skill_tasks WHERE id=?').get(id);
+        if (!row || row.order_id !== invocation.orderId)
+            throw new CommerceError('skill_task_not_found', 'Original skill Task not found');
+        return Task.fromJSON(JSON.parse(String(row.task_json)));
+    }
+    function executeProcess(payload) {
+        return new Promise((accept, reject) => {
+            const docker = settings.dockerContainer;
+            if (docker && !/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.test(docker))
+                throw new CommerceError('skill_container', 'Invalid Docker container name');
+            const child = docker
+                ? spawn('docker', ['exec', '-i', docker, settings.python, '-c', readFileSync(runner, 'utf8')], { stdio: ['pipe', 'pipe', 'pipe'], env: { PATH: process.env.PATH, HOME: process.env.HOME, DOCKER_CONFIG: process.env.DOCKER_CONFIG, DOCKER_HOST: process.env.DOCKER_HOST } })
+                : spawn(settings.python, [runner], { stdio: ['pipe', 'pipe', 'pipe'], env: { PATH: process.env.PATH, LANG: 'C.UTF-8', PYTHONUNBUFFERED: '1' } });
+            const chunks = [];
+            let size = 0;
+            const timeout = setTimeout(() => child.kill('SIGTERM'), 240000);
+            child.stdout.on('data', (chunk) => { size += chunk.length; if (size > 1024 * 1024)
+                child.kill('SIGTERM');
+            else
+                chunks.push(chunk); });
+            child.stderr.resume();
+            child.on('error', () => { clearTimeout(timeout); reject(new CommerceError('skill_runtime_start', 'Native skill runtime could not start')); });
+            child.on('close', code => {
+                clearTimeout(timeout);
+                try {
+                    if (code !== 0 || size > 1024 * 1024)
+                        throw Error();
+                    const result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                    if (typeof result.output !== 'string' || !result.output.trim() || result.framework !== settings.framework || !Array.isArray(result.tools) || result.tools.length)
+                        throw Error();
+                    accept(result);
+                }
+                catch {
+                    reject(new CommerceError('skill_runtime_failed', 'Native skill execution failed; inspect the original Task without resubmitting'));
+                }
+            });
+            child.stdin.on('error', () => { });
+            child.stdin.end(JSON.stringify(payload));
+        });
+    }
+    const runtime = {
+        list: () => installed().map(s => s.descriptor),
+        async send(name, input, invocation) {
+            const skills = installed(), selected = skills.find(s => s.descriptor.name === name);
+            if (!selected || selected.descriptor.digest !== invocation.grant.skillDigest)
+                throw new CommerceError('skill_changed', 'The purchased skill version is no longer installed');
+            invocation.grant.require(name);
+            const allowed = skills.filter(s => s.descriptor.name === name || s.descriptor.access === 'free');
+            allowed.forEach(s => invocation.grant.require(s.descriptor.name));
+            const binding = digest({ name, version: selected.descriptor.digest, caller: invocation.grant.caller, input, allowed: allowed.map(s => s.descriptor) });
+            const prior = db.prepare('SELECT id,binding FROM skill_tasks WHERE order_id=?').get(invocation.orderId);
+            if (prior) {
+                if (prior.binding !== binding)
+                    throw new CommerceError('skill_task_conflict', 'An order already identifies a different skill input');
+                return readTask(String(prior.id), invocation);
+            }
+            const id = randomUUID();
+            // A crash cannot cause a second native dispatch. The durable Task remains failed until owner inspection.
+            const pending = Task.fromJSON({ id, status: { state: 'TASK_STATE_WORKING' } });
+            db.prepare('INSERT INTO skill_tasks VALUES (?,?,?,?)').run(id, invocation.orderId, binding, JSON.stringify(Task.toJSON(pending)));
+            const operation = (async () => {
+                let task;
+                try {
+                    const result = await executeProcess({ settings: { ...settings, stateDirectory: join(settings.dockerStateDirectory ?? settings.stateDirectory, id) }, skillName: name, skills: allowed.map(s => ({ name: s.descriptor.name, instructions: s.instructions })), input });
+                    task = Task.fromJSON({ id, status: { state: 'TASK_STATE_COMPLETED' }, artifacts: [{ artifactId: 'result', name: name + '.md', parts: [{ text: result.output, mediaType: 'text/markdown' }] }], metadata: { skillName: name, skillDigest: selected.descriptor.digest, allowedSkills: allowed.map(s => s.descriptor.name), framework: settings.framework, tools: result.tools, sessionId: result.sessionId ?? id } });
+                }
+                catch (error) {
+                    task = Task.fromJSON({ id, status: { state: 'TASK_STATE_FAILED' }, metadata: { errorCode: error instanceof CommerceError ? error.code : 'skill_runtime_failed' } });
+                }
+                db.prepare('UPDATE skill_tasks SET task_json=? WHERE id=?').run(JSON.stringify(Task.toJSON(task)), id);
+                return task;
+            })();
+            inFlight.set(id, operation);
+            void operation.finally(() => inFlight.delete(id));
+            return pending;
+        },
+        async getTask(_name, id, invocation) { return readTask(id, invocation); },
+    };
+    const execute = skillScopedExecutor(runtime);
+    execute.skillCard = () => {
+        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/operations.d.ts

@@ -0,0 +1,22 @@
+export { inspectLocalAlerts, type LocalAlertOptions } from './alerts.js';
+export type InspectionView = 'attention' | 'refund-review';
+/** Local owner-only diagnostics: never opens a signer, vault, provider or network. */
+export declare function inspectLedger(path: string, after?: number, limit?: number, view?: InspectionView): {
+    role: string;
+    view: InspectionView;
+    total: number;
+    attentionCount: number;
+    refundReviewCount: number;
+    items: {
+        reason?: "confirmed_payment_failed_execution" | undefined;
+        cursor: number;
+        id: string;
+        paymentState: string;
+        executionState: string;
+        taskId: string | null;
+    }[];
+    nextCursor: number;
+    hasMore: boolean;
+    paymentPerformed: boolean;
+    refundPerformed: boolean;
+};

package/dist/commerce/operations.js

@@ -0,0 +1,39 @@
+import { DatabaseSync } from 'node:sqlite';
+import { lstatSync } from 'node:fs';
+import { CommerceError } from './types.js';
+export { inspectLocalAlerts } from './alerts.js';
+/** Local owner-only diagnostics: never opens a signer, vault, provider or network. */
+export function inspectLedger(path, after = 0, limit = 100, view = 'attention') {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0 || (process.getuid && stat.uid !== process.getuid()))
+        throw new CommerceError('private_file', 'Inspect an existing ledger owned only by the current user');
+    if (!Number.isSafeInteger(after) || after < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+        throw new CommerceError('inspection_cursor', 'Use a nonnegative row cursor and a limit from1 to100');
+    if (!['attention', 'refund-review'].includes(view))
+        throw new CommerceError('inspection_view', 'Use attention or refund-review inspection');
+    const db = new DatabaseSync(path, { readOnly: true });
+    try {
+        db.exec('PRAGMA query_only=ON; PRAGMA busy_timeout=1000');
+        const names = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all().map(row => row.name));
+        const role = names.has('buyer_purchases') ? 'buyer' : names.has('commerce_orders') ? 'seller' : null;
+        if (!role)
+            throw new CommerceError('store_version', 'Unrecognized commerce ledger');
+        const meta = role === 'buyer' ? 'buyer_meta' : 'commerce_meta', version = role === 'buyer' ? 1 : 2;
+        if (db.prepare(`SELECT version FROM ${meta}`).get()?.version !== version)
+            throw new CommerceError('store_version', 'Unsupported commerce ledger version');
+        const table = role === 'buyer' ? 'buyer_purchases' : 'commerce_orders';
+        const total = Number(db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get().n);
+        const attention = role === 'buyer' ? "json_extract(record_json,'$.state') IN ('signing','submitted','unknown') OR json_extract(record_json,'$.paymentState') IN ('reserved','unknown') OR json_extract(record_json,'$.executionState')='unknown'" : "payment_state IN ('settling','unknown') OR execution_state IN ('dispatching','unknown')";
+        const refundReview = role === 'buyer' ? "json_extract(record_json,'$.paymentState')='confirmed' AND json_extract(record_json,'$.executionState')='failed'" : "payment_state='confirmed' AND execution_state='failed'";
+        const filter = view === 'refund-review' ? refundReview : attention;
+        const selected = role === 'buyer' ? "rowid AS cursor,id,json_extract(record_json,'$.paymentState') AS payment_state,json_extract(record_json,'$.executionState') AS execution_state,json_extract(record_json,'$.task.id') AS task_id" : "rowid AS cursor,id,payment_state,execution_state,task_id";
+        const rows = db.prepare(`SELECT ${selected} FROM ${table} WHERE rowid>? AND (${filter}) ORDER BY rowid LIMIT ?`).all(after, limit + 1);
+        const page = rows.slice(0, limit).map(row => ({ cursor: Number(row.cursor), id: String(row.id), paymentState: String(row.payment_state), executionState: String(row.execution_state), taskId: typeof row.task_id === 'string' ? row.task_id : null, ...(view === 'refund-review' ? { reason: 'confirmed_payment_failed_execution' } : {}) }));
+        const attentionCount = Number(db.prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE ${attention}`).get().n);
+        const refundReviewCount = Number(db.prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE ${refundReview}`).get().n);
+        return { role, view, total, attentionCount, refundReviewCount, items: page, nextCursor: page.at(-1)?.cursor ?? after, hasMore: rows.length > limit, paymentPerformed: false, refundPerformed: false };
+    }
+    finally {
+        db.close();
+    }
+}