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

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

package/dist/commerce/envar.d.ts

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

package/dist/commerce/envar.js

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

package/dist/commerce/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,31 @@
+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;
+    discovery?: {
+        hermesHome: string;
+        enabledFromWeb: true;
+    };
+}
+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,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/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();
+    }
+}

package/dist/commerce/peer-proxy.js

@@ -230,7 +230,7 @@ export class A2APeerProxy {
         let raw = snapshot?.task
             ? structuredClone(snapshot.task)
             : {};
-        if (!code && ["failed", "unknown"].includes(String(row.phase))) {
+        if (!code && ["created", "attention", "failed", "unknown"].includes(String(row.phase))) {
             try {
                 const previous = JSON.parse(String(row.task_json));
                 if (typeof previous.metadata?.errorCode === "string")
@@ -251,9 +251,11 @@ export class A2APeerProxy {
                 status: {
                     state: needsApproval
                         ? "TASK_STATE_AUTH_REQUIRED"
-                        : failed
-                            ? "TASK_STATE_FAILED"
-                            : "TASK_STATE_WORKING",
+                        : phase === "attention"
+                            ? "TASK_STATE_INPUT_REQUIRED"
+                            : failed
+                                ? "TASK_STATE_FAILED"
+                                : "TASK_STATE_WORKING",
                 },
             };
         }
@@ -458,9 +460,13 @@ export class A2APeerProxy {
                         "peer_not_allowed",
                         "invalid_input",
                         "purchase_limit",
+                        "paid_quote_required",
+                        "offer_metadata_required",
+                        "quote_mismatch",
+                        "retired_revision",
                     ].includes(error.code);
                 this.phase(id, definitelyBlocked
-                    ? "failed"
+                    ? state === "previewing" ? "attention" : "failed"
                     : state === "confirming"
                         ? "unknown"
                         : state === "previewing"

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) {
@@ -43,7 +43,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,6 +2,8 @@
 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 './vault.js';

package/dist/commerce/runtime.js

@@ -2,6 +2,8 @@
 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 './vault.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;
@@ -36,6 +38,7 @@ export declare class CommerceServer {
     private running;
     private kickPending;
     private stopped;
+    private workerFailed;
     private waiters;
     private activeOrders;
     private recoveries;