@envarai/envarpay 0.2.0-alpha.2 → 0.2.0-alpha.20

package/dist/commerce/native-skills.js

@@ -0,0 +1,174 @@
+/** 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 > 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 }));
+    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);
+    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] })) });
+    };
+    return { execute, close: async () => { await Promise.allSettled(inFlight.values()); db.close(); } };
+}

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/operations.d.ts

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

package/dist/commerce/operations.js

@@ -1,31 +1,34 @@
+/** Owner-only, read-only inspection of original seller orders. */
 import { DatabaseSync } from 'node:sqlite';
 import { lstatSync } from 'node:fs';
 import { CommerceError } from './types.js';
-/** Local owner-only diagnostics: never opens a signer, vault, provider or network. */
-export function inspectLedger(path, after = 0, limit = 100) {
+export { inspectLocalAlerts } from './alerts.js';
+const ATTENTION = "payment_state IN ('settling','unknown') OR execution_state IN ('dispatching','unknown')";
+const REFUND_REVIEW = "payment_state='confirmed' AND execution_state='failed'";
+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');
+        throw new CommerceError('inspection_cursor', 'Use a nonnegative row cursor and a limit from 1 to 100');
+    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 filter = 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 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 }));
-        const attentionCount = Number(db.prepare(`SELECT COUNT(*) AS n FROM ${table} WHERE ${filter}`).get().n);
-        return { role, total, attentionCount, items: page, nextCursor: page.at(-1)?.cursor ?? after, hasMore: rows.length > limit, paymentPerformed: false };
+        if (db.prepare('SELECT version FROM commerce_meta').get()?.version !== 2)
+            throw new CommerceError('store_version', 'Unsupported seller ledger version');
+        const total = Number(db.prepare('SELECT COUNT(*) AS n FROM commerce_orders').get().n);
+        const filter = view === 'refund-review' ? REFUND_REVIEW : ATTENTION;
+        const rows = db.prepare(`SELECT rowid AS cursor,id,payment_state,execution_state,task_id FROM commerce_orders 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 commerce_orders WHERE ${ATTENTION}`).get().n);
+        const refundReviewCount = Number(db.prepare(`SELECT COUNT(*) AS n FROM commerce_orders WHERE ${REFUND_REVIEW}`).get().n);
+        return { role: 'seller', view, total, attentionCount, refundReviewCount, items: page, nextCursor: page.at(-1)?.cursor ?? after, hasMore: rows.length > limit, paymentPerformed: false, refundPerformed: false };
     }
     finally {
         db.close();

package/dist/commerce/pricing.d.ts

@@ -7,6 +7,5 @@ export declare function buildQuote(config: CommerceConfig, args: {
     input: Input;
     now?: Date;
     ttlSeconds?: number;
-    stripeRecipient?: string;
 }): Readonly<PriceQuote>;
 export declare function assertQuoteRequest(quote: Readonly<PriceQuote>, caller: string, messageId: string, input: Input, now?: Date): void;

package/dist/commerce/pricing.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import addFormatsImport from 'ajv-formats';
-import { atomic, currencyOf, digest } from './config.js';
+import { atomic, currencyOf, digest, serviceTermsDigest } from './config.js';
 import { CommerceError } from './types.js';
 const addFormats = addFormatsImport;
 export function buildQuote(config, args) {
@@ -33,9 +33,7 @@ export function buildQuote(config, args) {
     if (amount >= 2n ** 256n)
         throw new CommerceError('invalid_amount', 'Quoted amount is too large');
     const profile = offer.paymentProfile ? config.paymentProfiles[offer.paymentProfile] : null;
-    const recipient = profile?.adapter === 'x402' ? profile.payTo : profile ? args.stripeRecipient : null;
-    if (profile?.adapter === 'mpp' && !recipient)
-        throw new CommerceError('merchant_not_ready', 'Resolve and verify the Stripe merchant before quoting');
+    const recipient = profile?.accountRef ?? null;
     const now = args.now ?? new Date();
     const ttl = args.ttlSeconds ?? 600;
     if (!Number.isInteger(ttl) || ttl < 1 || ttl > 3600 || !Number.isFinite(now.getTime()))
@@ -43,7 +41,7 @@ export function buildQuote(config, args) {
     const quote = {
         quoteVersion: 1, quoteId: randomUUID(), caller: args.caller, serviceId: service.id,
         serviceRevision: service.revision, offerId: offer.id, messageId: args.messageId,
-        inputDigest: digest(args.input), termsDigest: digest({ contract: service.contract, offer, profile }),
+        inputDigest: digest(args.input), termsDigest: serviceTermsDigest(config.configVersion, service, offer, profile),
         issuedAt: now.toISOString(), expiresAt: new Date(now.getTime() + ttl * 1000).toISOString(),
         amount: amount.toString(), currency: profile ? currencyOf(profile) : null,
         recipient: recipient ?? null, paymentProfile: profile ? structuredClone(profile) : null,

package/dist/commerce/runtime.d.ts

@@ -2,7 +2,9 @@
 export * from './store.js';
 export * from './server.js';
 export * from './upstream.js';
+export * from './skill-gate.js';
+export * from './native-skills.js';
 export * from './http.js';
-export * from './x402.js';
+export * from './envar-balance.js';
 export * from './vault.js';
-export * from './chain.js';
+export * from './external-agent.js';

package/dist/commerce/runtime.js

@@ -2,7 +2,9 @@
 export * from './store.js';
 export * from './server.js';
 export * from './upstream.js';
+export * from './skill-gate.js';
+export * from './native-skills.js';
 export * from './http.js';
-export * from './x402.js';
+export * from './envar-balance.js';
 export * from './vault.js';
-export * from './chain.js';
+export * from './external-agent.js';

package/dist/commerce/server.d.ts

@@ -1,9 +1,11 @@
-import { Task, SendMessageRequest } from '@a2a-js/sdk';
+import { AgentCard, Task, SendMessageRequest } from '@a2a-js/sdk';
 import { ServerCallContext } from '@a2a-js/sdk/server';
 import { CommerceStore, type OrderRecord, type ContinuationRecord, type RemoteTaskReference } from './store.js';
 import { type CommerceConfig, type Input, type Service } from './types.js';
 export interface ExecuteOrder {
     (order: OrderRecord, service: Service): AsyncIterable<Task>;
+    assertSkill?: (service: Service) => unknown;
+    skillCard?: () => AgentCard;
     continue?: (order: OrderRecord, service: Service, continuation: ContinuationRecord, remote: RemoteTaskReference) => AsyncIterable<Task>;
     recover?: (order: OrderRecord, service: Service, remote: RemoteTaskReference) => Promise<Task>;
     remoteInterface?: (task: Task) => string | undefined;
@@ -21,7 +23,6 @@ export interface CommerceServerOptions {
             headers: Record<string, string>;
         }>;
     };
-    stripeRecipientFor?: (accountRef: string) => string | undefined;
     ownershipChallenges?: Readonly<Record<string, string>>;
     onError?: (code: string, orderId?: string) => void;
 }

package/dist/commerce/server.js

@@ -1,7 +1,7 @@
 import { timingSafeEqual } from 'node:crypto';
 import { AgentCard, Role, Task, TaskState, SendMessageRequest } from '@a2a-js/sdk';
 import { DefaultRequestHandler, JsonRpcTransportHandler, ServerCallContext } from '@a2a-js/sdk/server';
-import { RequestMalformedError, TaskNotFoundError, UnsupportedOperationError } from '@a2a-js/sdk/errors';
+import { ContentTypeNotSupportedError, RequestMalformedError, TaskNotFoundError, UnsupportedOperationError, VersionNotSupportedError } from '@a2a-js/sdk/errors';
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import addFormatsImport from 'ajv-formats';
 import { createOfferCard, offerPath } from './card.js';
@@ -188,6 +188,11 @@ export class CommerceServer {
         if (this.stopped)
             throw new CommerceError('server_draining', 'Cannot apply configuration while stopping');
         const config = loadCommerceConfig(value);
+        for (const service of config.services.filter(s => s.execution.type === 'skill')) {
+            if (!this.options.execute.assertSkill)
+                throw new CommerceError('skill_gate_required', 'Skill services require an enforcing skill runtime');
+            this.options.execute.assertSkill(service);
+        }
         if (config.agent.id !== this.currentConfig.agent.id)
             throw new CommerceError('config_agent_changed', 'Runtime Agent identity cannot change');
         const history = this.store.catalogHistory();
@@ -207,7 +212,7 @@ export class CommerceServer {
         const routes = new Map();
         for (const entry of snapshots.values())
             for (const offer of entry.service.offers) {
-                const service = entry.service, historical = { ...config, paymentProfiles: entry.profiles, services: [service] };
+                const service = entry.service, historical = { ...config, configVersion: (service.execution.type === 'skill' ? 2 : 1), paymentProfiles: entry.profiles, services: [service] };
                 const card = createOfferCard(historical, service.id, offer.id, this.options.origin);
                 const active = config.services.some(s => s.id === service.id && s.revision === service.revision);
                 routes.set(offerPath(service.id, service.revision, offer.id), { card, rpc: new JsonRpcTransportHandler(new OrderHandler(this, service, offer.id, card, this.store, active)), tenant: `${service.id}:${service.revision}`, service, offerId: offer.id, active });
@@ -223,17 +228,22 @@ export class CommerceServer {
     quote(service, offerId, caller, messageId, input) {
         if (!this.activeRevision(service))
             throw new CommerceError('retired_revision', 'This service revision is retired; recover original Tasks');
+        if (service.execution.type === 'skill')
+            this.options.execute.assertSkill(service);
         const frozen = this.store.catalogHistory().find(entry => entry.service.id === service.id && entry.service.revision === service.revision);
         if (!frozen)
             throw new CommerceError('unknown_revision', 'Service revision is not registered');
-        const config = { ...this.currentConfig, paymentProfiles: frozen.profiles, services: [frozen.service] }, offer = frozen.service.offers.find(o => o.id === offerId);
-        const profile = offer.paymentProfile ? frozen.profiles[offer.paymentProfile] : undefined;
-        return buildQuote(config, { serviceId: service.id, offerId, caller, messageId, input, ...(profile?.adapter === 'mpp' ? { stripeRecipient: this.options.stripeRecipientFor?.(profile.accountRef) } : {}) });
+        const config = { ...this.currentConfig, paymentProfiles: frozen.profiles, services: [frozen.service] };
+        return buildQuote(config, { serviceId: service.id, offerId, caller, messageId, input });
     }
     async handle(request) {
         const url = new URL(request.url);
         if (url.origin !== new URL(this.options.origin).origin)
             return Response.json({ error: 'invalid_host' }, { status: 421 });
+        if (request.method === 'GET' && url.pathname === '/.well-known/agent-card.json' && this.options.execute.skillCard)
+            return Response.json(AgentCard.toJSON(this.options.execute.skillCard()), { headers: { 'Cache-Control': 'no-store' } });
+        if (url.pathname === '/a2a' && this.options.execute.skillCard)
+            return Response.json({ error: 'service_required', message: 'Select a named service offer to invoke a skill' }, { status: 400 });
         if (request.method === 'GET' && ['/healthz', '/readyz'].includes(url.pathname)) {
             let ready = !this.stopped;
             if (url.pathname === '/readyz') {
@@ -267,8 +277,6 @@ export class CommerceServer {
         const caller = await this.options.authenticate(request);
         if (!caller)
             return Response.json({ error: 'authentication_required' }, { status: 401, headers: { 'WWW-Authenticate': 'Bearer', 'Cache-Control': 'no-store' } });
-        if (request.headers.get('A2A-Version') !== '1.0')
-            return Response.json({ error: 'A2A-Version 1.0 required' }, { status: 400 });
         if (Number(request.headers.get('Content-Length') ?? 0) > 1024 * 1024)
             return Response.json({ error: 'request_too_large' }, { status: 413 });
         let size = 0;
@@ -291,12 +299,18 @@ export class CommerceServer {
         let requestId = null;
         try {
             const raw = JSON.parse(body);
-            if (raw.method === 'SendMessage' && this.workerFailed)
-                return Response.json({ error: 'worker_unavailable' }, { status: 503, headers: { 'Cache-Control': 'no-store' } });
             if (!raw || Array.isArray(raw) || typeof raw !== 'object')
                 throw new RequestMalformedError('A single JSONRPC object is required');
             requestId = raw.id ?? null;
             const params = raw.params;
+            // Parse only the bounded envelope to preserve its request ID. Reject these
+            // transport conditions before any quote, payment gate or Task dispatch.
+            if (request.headers.get('A2A-Version') !== '1.0')
+                throw new VersionNotSupportedError('This service supports A2A-Version 1.0');
+            if (request.headers.get('Content-Type')?.split(';', 1)[0]?.trim().toLowerCase() !== 'application/json')
+                throw new ContentTypeNotSupportedError('Send application/json to this JSON-RPC endpoint');
+            if (raw.method === 'SendMessage' && this.workerFailed)
+                return Response.json({ error: 'worker_unavailable' }, { status: 503, headers: { 'Cache-Control': 'no-store' } });
             if (params && typeof params === 'object' && 'tenant' in params && params.tenant !== route.tenant)
                 return Response.json({ jsonrpc: '2.0', id: raw.id ?? null, error: { code: -32602, message: 'Invalid tenant' } }, { status: 200 });
             let paymentHeaders = {};
@@ -313,6 +327,8 @@ export class CommerceServer {
                     if (!prior && !this.activeRevision(route.service))
                         throw new UnsupportedOperationError('This service revision is retired');
                     const order = prior ?? this.store.ensureQuote(this.quote(route.service, route.offerId, caller, message.message.messageId, input), input);
+                    if (route.service.execution.type === 'skill' && !['confirmed', 'not_required'].includes(order.paymentState))
+                        this.options.execute.assertSkill(route.service);
                     if (order.paymentState !== 'not_required') {
                         const gate = await this.options.paymentGate.handle(new Request(request.url, { method: 'POST', headers: request.headers, body }), order);
                         if ('response' in gate)
@@ -329,7 +345,7 @@ export class CommerceServer {
         }
         catch (error) {
             const mapped = error instanceof CommerceError ? { code: -32000, message: error.message, data: { code: error.code } } : JsonRpcTransportHandler.mapToJSONRPCError(error);
-            return Response.json({ jsonrpc: '2.0', id: requestId, error: mapped }, { headers: { 'Cache-Control': 'no-store' } });
+            return Response.json({ jsonrpc: '2.0', id: requestId, error: mapped }, { headers: { 'A2A-Version': '1.0', 'Cache-Control': 'no-store' } });
         }
     }
     async continueTask(params, input, service, offerId, context) {

package/dist/commerce/setup.d.ts

@@ -0,0 +1,25 @@
+export interface SetupBundle {
+    version: 1;
+    agentId: string;
+    agentName: string;
+    runtimeAgentId: string;
+    platformOrigin: string;
+    token: string;
+    expiresAt: string;
+}
+export declare function parseSetupBundle(raw: unknown): SetupBundle;
+export declare function prepareTextSkill(source: string, destination: string, name: string): void;
+export declare function setupAgent(options: {
+    framework?: "hermes" | "openclaw";
+    managed?: boolean;
+    file: string;
+    directory?: string;
+    container?: string;
+    python?: string;
+    home?: string;
+    automatic?: {
+        port: number;
+        origin: string;
+    };
+}): Promise<void>;
+export declare const setupHermes: (options: Parameters<typeof setupAgent>[0]) => Promise<void>;