@envarai/envarpay 0.1.0-alpha.3 → 0.2.0-alpha.10

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();
+    }
+}

package/dist/commerce/peer-proxy.d.ts

@@ -0,0 +1,44 @@
+import { AgentCard, Task, type SendMessageRequest } from "@a2a-js/sdk";
+import { CommerceBuyer } from "./buyer.js";
+export interface PeerProxyOptions {
+    buyer: CommerceBuyer;
+    buyerCaller: string;
+    peerId: string;
+    offerId: string;
+    origin: string;
+    stateDirectory: string;
+    tokens: Readonly<Record<string, string>>;
+    label?: string;
+    waitMilliseconds?: number;
+    /** Explicit opt-in for an isolated Docker/private HTTP network; public deployments require HTTPS. */
+    allowPrivateHttp?: boolean;
+}
+/** The proxy token is never a wallet-management token. One proxy is bound to one approved peer/offer. */
+export declare class A2APeerProxy {
+    private readonly options;
+    readonly origin: string;
+    readonly card: AgentCard;
+    private readonly db;
+    private readonly lock;
+    private readonly rpc;
+    private readonly authenticate;
+    private readonly cardUrl;
+    private readonly waitMs;
+    private readonly active;
+    private stopped;
+    private closed;
+    constructor(options: PeerProxyOptions);
+    private row;
+    private phase;
+    private projection;
+    private exclusive;
+    private snapshot;
+    private wait;
+    send(params: SendMessageRequest, caller: string): Promise<Task>;
+    read(id: string, caller: string): Promise<Task>;
+    handle(request: Request): Promise<Response>;
+    assertListenHost(host: string): void;
+    stop(): Promise<void>;
+    close(): void;
+}
+export declare function listenPeerProxy(proxy: A2APeerProxy, host?: string, port?: number): import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;