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

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';
@@ -171,6 +171,7 @@ export class CommerceServer {
     running = false;
     kickPending = false;
     stopped = false;
+    workerFailed = false;
     waiters = new Map();
     activeOrders = new Set();
     recoveries = new Map();
@@ -187,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();
@@ -206,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 });
@@ -222,6 +228,8 @@ 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');
@@ -233,8 +241,23 @@ export class CommerceServer {
         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' && ['/healthz', '/readyz'].includes(url.pathname))
-            return Response.json({ status: this.stopped ? 'draining' : 'ready' }, { status: this.stopped ? 503 : 200, headers: { 'Cache-Control': 'no-store' } });
+        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') {
+                ready = ready && !this.workerFailed;
+                try {
+                    this.store.assertReady();
+                }
+                catch {
+                    ready = false;
+                }
+            }
+            return Response.json({ status: ready ? 'ready' : this.stopped ? 'draining' : 'unavailable' }, { status: ready ? 200 : 503, headers: { 'Cache-Control': 'no-store' } });
+        }
         const proof = /^\/\.well-known\/envar\/([0-9a-f-]{36})$/.exec(url.pathname);
         if (request.method === 'GET' && proof) {
             const challenge = this.options.ownershipChallenges?.[proof[1]];
@@ -255,8 +278,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;
@@ -283,6 +304,14 @@ export class CommerceServer {
                 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 = {};
@@ -299,6 +328,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)
@@ -315,7 +346,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) {
@@ -393,14 +424,14 @@ export class CommerceServer {
         return projected;
     }
     schedule() {
-        if (this.stopped)
+        if (this.stopped || this.workerFailed)
             return;
         if (this.running) {
             this.kickPending = true;
             return;
         }
         this.running = true;
-        void this.drain().catch(() => this.options.onError?.('worker_failure')).finally(() => { this.running = false; if (this.kickPending) {
+        void this.drain().catch(() => { this.workerFailed = true; this.options.onError?.('worker_failure'); }).finally(() => { this.running = false; if (this.kickPending) {
             this.kickPending = false;
             this.schedule();
         } });

package/dist/commerce/setup.d.ts

@@ -0,0 +1,18 @@
+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 setupHermes(options: {
+    file: string;
+    directory?: string;
+    container?: string;
+    python?: string;
+    home?: string;
+}): Promise<void>;

package/dist/commerce/setup.js

@@ -0,0 +1,344 @@
+/** Guided local installation. Platform input is data, never a shell command or wallet policy. */
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync, cpSync, mkdtempSync, renameSync, rmSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { readInstalledSkills } from "./native-skills.js";
+import { loadCommerceConfig, validateUrl } from "./config.js";
+import { CommerceError } from "./types.js";
+const ID = /^[a-z][a-z0-9-]{0,63}$/, CONTAINER = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/;
+export function parseSetupBundle(raw) {
+    const v = raw;
+    if (!v ||
+        v.version !== 1 ||
+        !/^[0-9a-f-]{36}$/.test(v.agentId) ||
+        !ID.test(v.runtimeAgentId) ||
+        typeof v.agentName !== "string" ||
+        v.agentName.length > 120 ||
+        !/^envar_agent_[A-Za-z0-9_-]{32,100}$/.test(v.token) ||
+        !Number.isFinite(Date.parse(v.expiresAt)) ||
+        Date.parse(v.expiresAt) <= Date.now())
+        throw new CommerceError("setup_file", "Download a fresh Agent setup file from Envar");
+    const origin = validateUrl(v.platformOrigin);
+    if (origin.origin !== v.platformOrigin)
+        throw new CommerceError("setup_origin", "Use the platform HTTPS origin");
+    return v;
+}
+export function prepareTextSkill(source, destination, name) {
+    if (!ID.test(name) || existsSync(destination))
+        throw new CommerceError("setup_skill", "Choose a new exact skill name");
+    const stat = lstatSync(source);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new CommerceError("setup_skill", "Choose a real skill directory");
+    cpSync(source, destination, {
+        recursive: true,
+        filter: (path) => {
+            const item = lstatSync(path);
+            if (item.isSymbolicLink())
+                throw new CommerceError("setup_skill", "Skill symlinks are unsupported");
+            if (item.isFile() &&
+                !/\.(md|txt)$/i.test(path) &&
+                !path.endsWith("/LICENSE"))
+                throw new CommerceError("setup_skill", "Choose a text-only package without scripts or binaries");
+            return true;
+        },
+    });
+    const file = join(destination, "SKILL.md"), original = readFileSync(file, "utf8");
+    if (!original.startsWith("---\n") && !original.startsWith("---\r\n"))
+        throw new CommerceError("setup_skill", "Skill needs YAML frontmatter");
+    const adapted = original.replace(/^(---\r?\n)([\s\S]*?)(\r?\n---)/, (_all, open, front, close) => open +
+        front.replace(/^envar-runtime:.*\r?\n?/gm, "") +
+        "\nenvar-runtime: instruction-only" +
+        close);
+    writeFileSync(file, adapted +
+        "\n\n## Service execution\nUse the supplied buyer input as the complete product context. Bundled Markdown references are included in the task context. Return text in the A2A result. Do not browse, access files, run scripts, or invoke other skills. If information is missing, state what is missing; do not invent it.\n", { mode: 0o600 });
+}
+function privateJson(path, value) {
+    writeFileSync(path, JSON.stringify(value, null, 2) + "\n", {
+        mode: 0o600,
+        flag: "wx",
+    });
+}
+export async function setupHermes(options) {
+    const file = resolve(options.file), info = lstatSync(file);
+    if (!info.isFile() || info.isSymbolicLink() || info.size > 16384)
+        throw new CommerceError("setup_file", "Use the downloaded setup JSON file");
+    const bundle = parseSetupBundle(JSON.parse(readFileSync(file, "utf8")));
+    if (options.container && !CONTAINER.test(options.container))
+        throw new CommerceError("setup_container", "Use a Docker container name");
+    if (!process.stdin.isTTY)
+        throw new CommerceError("setup_terminal", "Run setup in an interactive terminal to select skills");
+    chmodSync(file, 0o600);
+    const prompt = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const ask = async (label, fallback = "") => (await prompt.question(`${label}${fallback ? ` [${fallback}]` : ""}: `)).trim() || fallback;
+    let staging;
+    try {
+        console.log(`\nConnect ${bundle.agentName} to ${bundle.platformOrigin}\nModel credentials and tasks remain on this machine. Start with free services; no wallet is created.\n`);
+        if ((await ask("Continue? (yes/no)", "no")).toLowerCase() !== "yes")
+            return;
+        const directory = resolve(options.directory ?? join(homedir(), ".envarpay", bundle.agentId));
+        if (existsSync(directory))
+            throw new CommerceError("setup_exists", "This Agent already has a local directory. Use its start script; never reset its ledger.");
+        let python = options.python;
+        const compatibility = 'import inspect;from run_agent import AIAgent;assert all(k in inspect.signature(AIAgent).parameters for k in ["skip_context_files","skip_memory","skip_background_review","ephemeral_system_prompt","enabled_toolsets"])';
+        if (!python && options.container) {
+            for (const candidate of [
+                "/opt/hermes-latest/bin/python",
+                "/opt/hermes/.venv/bin/python",
+                "python3",
+            ]) {
+                try {
+                    execFileSync("docker", ["exec", options.container, candidate, "-c", compatibility], { stdio: "pipe", timeout: 60000 });
+                    python = candidate;
+                    break;
+                }
+                catch {
+                    /* try the next compatible installed interpreter */
+                }
+            }
+            if (!python)
+                throw new CommerceError("setup_runtime", "No compatible Hermes interpreter found in this container. Update Hermes or pass --python PATH.");
+        }
+        python ??= await ask("Hermes Python executable", join(homedir(), "hermes-agent", ".venv", "bin", "python"));
+        const probeSource = readFileSync(new URL("../../examples/hermes-setup-probe.py", import.meta.url), "utf8");
+        let probe;
+        try {
+            if (options.container)
+                execFileSync("docker", ["exec", options.container, python, "-c", compatibility], { stdio: "pipe", timeout: 60000 });
+            else
+                execFileSync(python, ["-c", compatibility], {
+                    stdio: "pipe",
+                    timeout: 60000,
+                });
+            const args = ["-c", probeSource, ...(options.home ? [options.home] : [])];
+            const data = options.container
+                ? execFileSync("docker", ["exec", options.container, python, ...args], {
+                    stdio: "pipe",
+                    timeout: 30000,
+                    maxBuffer: 2 * 1024 * 1024,
+                })
+                : execFileSync(python, args, {
+                    stdio: "pipe",
+                    timeout: 30000,
+                    maxBuffer: 2 * 1024 * 1024,
+                });
+            probe = JSON.parse(data.toString());
+        }
+        catch {
+            throw new CommerceError("setup_model", "Could not read Hermes. Check the container/Python path and configure an OpenAI-compatible model in Hermes first.");
+        }
+        const candidates = probe.skills.filter((s) => s.textPackage && ID.test(s.name));
+        console.log(`Model: ${probe.model}\nInstalled text packages (review their instructions before selecting):`);
+        candidates.forEach((skill, i) => console.log(`${i + 1}. ${skill.name} — ${skill.description.replace(/[\r\n\x1b]/g, " ").slice(0, 160)}`));
+        console.log('Newly installed Skills will be discovered privately. Enable each one from the Envar service page after reviewing text-only compatibility.');
+        const selected = (await ask("Optional: enable existing text Skills now (comma separated, Enter to skip)"))
+            .split(",")
+            .map((s) => s.trim()).filter(Boolean);
+        if (selected.length > 32 ||
+            new Set(selected).size !== selected.length ||
+            selected.some((name) => !candidates.some((s) => s.name === name)))
+            throw new CommerceError("setup_skills", "Choose installed skill names from the list");
+        console.log("This adapter supplies buyer text and bundled Markdown references. Browser, script, file and API tools are disabled. Original Hermes skills are preserved; a service copy is created.");
+        if (selected.length &&
+            (await ask("Do these selected skills work with text input and text output only? (yes/no)", "no")).toLowerCase() !== "yes")
+            return;
+        const port = Number(await ask("Local service port", "4020"));
+        if (!Number.isInteger(port) || port < 1024 || port > 65535)
+            throw new CommerceError("setup_port", "Choose a local port from 1024 to 65535");
+        let origin;
+        const tunnelMode = await ask("Public HTTPS: use an existing ngrok session or your own reverse proxy? (ngrok/url)", "ngrok");
+        if (tunnelMode === "ngrok") {
+            const api = new URL(await ask("Local ngrok API", "http://127.0.0.1:4040"));
+            if (api.protocol !== "http:" ||
+                api.hostname !== "127.0.0.1" ||
+                api.username ||
+                api.password ||
+                api.pathname !== "/")
+                throw new CommerceError("setup_tunnel", "Use the local ngrok API on 127.0.0.1");
+            const name = `envarpay-${bundle.agentId}`, addr = `http://127.0.0.1:${port}`;
+            const inventory = await fetch(new URL("/api/tunnels", api), {
+                signal: AbortSignal.timeout(10000),
+            });
+            if (!inventory.ok)
+                throw new CommerceError("setup_tunnel", "Start ngrok first, or choose your own HTTPS URL");
+            const existing = (await inventory.json()).tunnels.find((t) => t.name === name);
+            if (existing) {
+                if (existing.config.addr !== addr)
+                    throw new CommerceError("setup_tunnel", "The existing Agent tunnel uses another local port. Keep its original port.");
+                origin = existing.public_url;
+            }
+            else {
+                const response = await fetch(new URL("/api/tunnels", api), {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({
+                        name,
+                        proto: "http",
+                        addr,
+                        schemes: ["https"],
+                        inspect: false,
+                    }),
+                    signal: AbortSignal.timeout(15000),
+                });
+                if (!response.ok)
+                    throw new CommerceError("setup_tunnel", "Could not create a dedicated tunnel. Check ngrok or choose your own HTTPS URL. Existing tunnels were preserved.");
+                origin = (await response.json()).public_url;
+            }
+        }
+        else if (tunnelMode === "url") {
+            origin = await ask(`Public HTTPS origin (forward to http://127.0.0.1:${port})`);
+        }
+        else
+            throw new CommerceError("setup_tunnel", "Choose ngrok or url");
+        const publicUrl = validateUrl(origin);
+        if (publicUrl.origin !== origin ||
+            (publicUrl.port && publicUrl.port !== "443"))
+            throw new CommerceError("setup_origin", "Use an HTTPS origin on port443");
+        // Only publish a complete new setup directory. An interrupted setup cannot strand
+        // the owner behind setup_exists or overwrite a prior ledger.
+        mkdirSync(resolve(directory, ".."), { recursive: true, mode: 0o700 });
+        staging = mkdtempSync(directory + ".setup-");
+        chmodSync(staging, 0o700);
+        const skillsDirectory = join(staging, "skills");
+        mkdirSync(skillsDirectory, { mode: 0o700 });
+        for (const name of selected) {
+            const skill = candidates.find((s) => s.name === name);
+            if (options.container) {
+                const incoming = join(staging, `incoming-${name}`);
+                execFileSync("docker", ["cp", `${options.container}:${skill.path}`, incoming], { stdio: "pipe", timeout: 30000 });
+                prepareTextSkill(incoming, join(skillsDirectory, name), name);
+                rmSync(incoming, { recursive: true });
+            }
+            else
+                prepareTextSkill(skill.path, join(skillsDirectory, name), name);
+        }
+        readInstalledSkills(skillsDirectory, [], origin + "/.well-known/agent-card.json");
+        const access = randomBytes(36).toString("base64url");
+        let apiKeyFile = probe.apiKeyFile;
+        if (!apiKeyFile) {
+            if (options.container) {
+                apiKeyFile = join(probe.home, "envarpay-secrets", bundle.agentId, "model.key");
+                // Key bytes travel through stdin, never process arguments or console output.
+                const writeKey = "import sys,os;from pathlib import Path;p=Path(sys.argv[1]);p.parent.mkdir(parents=True,exist_ok=True,mode=0o700);fd=os.open(p,os.O_WRONLY|os.O_CREAT|os.O_EXCL,0o600);os.write(fd,sys.stdin.buffer.read());os.close(fd)";
+                try {
+                    execFileSync("docker", [
+                        "exec",
+                        "-i",
+                        options.container,
+                        python,
+                        "-c",
+                        writeKey,
+                        apiKeyFile,
+                    ], {
+                        input: probe.apiKey,
+                        stdio: ["pipe", "pipe", "pipe"],
+                        timeout: 15000,
+                    });
+                }
+                catch {
+                    throw new CommerceError("setup_model", "Could not save the local model credential. Inspect the Agent-specific envarpay-secrets directory before retrying.");
+                }
+            }
+            else {
+                apiKeyFile = join(directory, "model.key");
+                writeFileSync(join(staging, "model.key"), probe.apiKey, {
+                    mode: 0o600,
+                    flag: "wx",
+                });
+            }
+        }
+        const stateDirectory = join(directory, "tasks");
+        mkdirSync(join(staging, "tasks"), { mode: 0o700 });
+        const dockerStateDirectory = options.container
+            ? join(probe.home, "envarpay-tasks", bundle.agentId)
+            : undefined;
+        const config = loadCommerceConfig({
+            configVersion: 2,
+            agent: { id: bundle.runtimeAgentId, name: bundle.agentName },
+            paymentProfiles: {},
+            services: [],
+        });
+        privateJson(join(staging, "seller.json"), config);
+        privateJson(join(staging, "credentials.json"), {
+            callers: { [access]: "owner" },
+            upstreams: {},
+            skills: {
+                framework: "hermes",
+                discovery: { hermesHome: probe.home, enabledFromWeb: true },
+                skillsDirectory: join(directory, "skills"),
+                freeSkills: [],
+                stateDirectory,
+                python,
+                model: probe.model,
+                baseUrl: probe.baseUrl,
+                apiKeyFile,
+                ...(options.container
+                    ? { dockerContainer: options.container, dockerStateDirectory }
+                    : {}),
+            },
+        });
+        writeFileSync(join(staging, "envar.token"), bundle.token, {
+            mode: 0o600,
+            flag: "wx",
+        });
+        privateJson(join(staging, "envar.json"), {
+            policy: {
+                enabled: true,
+                platformOrigin: bundle.platformOrigin,
+                agentId: bundle.agentId,
+                runtimeAgentId: bundle.runtimeAgentId,
+                acceptUpdates: true,
+                allowedServices: selected,
+                allowedUpstreamOrigins: [origin],
+                allowedX402: [],
+                allowedMppAccounts: [],
+            },
+            stateDirectory: join(directory, "envar-state"),
+            configDirectory: join(directory, "envar-configs"),
+        });
+        privateJson(join(staging, "connection.json"), {
+            version: 1,
+            agentId: bundle.agentId,
+            url: origin + "/.well-known/agent-card.json",
+            authToken: access,
+        });
+        const cli = fileURLToPath(new URL("./cli.js", import.meta.url));
+        const args = [
+            cli,
+            "serve",
+            "--config",
+            join(directory, "seller.json"),
+            "--credentials",
+            join(directory, "credentials.json"),
+            "--state",
+            join(directory, "seller.sqlite3"),
+            "--origin",
+            origin,
+            "--host",
+            "127.0.0.1",
+            "--port",
+            String(port),
+            "--envar-config",
+            join(directory, "envar.json"),
+            "--envar-credentials",
+            join(directory, "envar.token"),
+        ];
+        const start = join(directory, "start.mjs");
+        writeFileSync(join(staging, "start.mjs"), `import {spawn} from 'node:child_process';\nconst child=spawn(${JSON.stringify(process.execPath)},${JSON.stringify(args)},{stdio:'inherit'});\nfor(const signal of ['SIGTERM','SIGINT'])process.on(signal,()=>child.kill(signal));\nchild.on('exit',code=>process.exit(code??1));\n`, { mode: 0o700, flag: "wx" });
+        writeFileSync(join(staging, "README.md"), `# ${bundle.agentName}\n\nStart: node ${JSON.stringify(start)}\n\nKeep the terminal, Hermes, and HTTPS tunnel running. Import connection.json in the Envar setup page, then check the connection. Choose a skill and save a free service. Request publication; this process applies the selected service automatically. Return to Envar and check/publish.\n\nOnly free service updates are authorized. Receiving and payment setup is separate. Platform token expires ${bundle.expiresAt}. Keep the original files and ledger when restarting.\n`, { mode: 0o600, flag: "wx" });
+        renameSync(staging, directory);
+        staging = undefined;
+        console.log(`\nReady. Start the local service:\n${process.execPath} ${JSON.stringify(start)}\n\nThen import this connection file in Envar:\n${join(directory, "connection.json")}\n\nKeep the service and HTTPS tunnel online. No task or payment was performed.`);
+    }
+    finally {
+        prompt.close();
+        if (staging)
+            rmSync(staging, { recursive: true, force: true });
+    }
+}

package/dist/commerce/skill-gate.d.ts

@@ -0,0 +1,54 @@
+import { AgentCard, Task } from '@a2a-js/sdk';
+import { type Input } from './types.js';
+import type { ExecuteOrder } from './server.js';
+import type { OrderRecord } from './store.js';
+/** The name is the service ID. The digest pins the installed skill version. */
+export interface SkillDescriptor {
+    name: string;
+    digest: string;
+    cardUrl: string;
+    access: 'free' | 'paid';
+    description?: string;
+}
+/** The Agent-owned adapter may expose one private, authenticated A2A Card per skill. */
+export declare function createSkillCard(descriptor: SkillDescriptor, interfaceUrl: string): AgentCard;
+/** In-process authority passed only after the seller has confirmed payment or a free offer. */
+export declare class SkillGrant {
+    #private;
+    readonly skillName: string;
+    readonly skillDigest: string;
+    readonly orderId: string;
+    readonly caller: string;
+    readonly messageId: string;
+    readonly inputDigest: string;
+    constructor(order: OrderRecord, descriptor: SkillDescriptor, freeSkills: ReadonlySet<string>, messageId?: string);
+    /** A purchased task may use its own skill and declared free skills, never another paid skill. */
+    require(skillName: string): void;
+}
+export interface SkillInvocation {
+    orderId: string;
+    messageId: string;
+    taskId?: string;
+    contextId?: string;
+    grant: SkillGrant;
+}
+/**
+ * An Agent-owned adapter. It must route by the passed exact skill name and use
+ * grant.require() for every nested skill invocation. Raw paid skills stay private.
+ */
+export interface SkillRuntime {
+    list(): readonly SkillDescriptor[];
+    send(skillName: string, input: Input, invocation: SkillInvocation): Promise<Task>;
+    getTask(skillName: string, taskId: string, invocation: SkillInvocation): Promise<Task>;
+}
+export interface SkillHandler {
+    descriptor: SkillDescriptor;
+    send(input: Input, invocation: SkillInvocation & {
+        callSkill(name: string, input: Input): Promise<Task>;
+    }): Promise<Task>;
+    getTask(taskId: string, invocation: SkillInvocation): Promise<Task>;
+}
+/** Reference in-process adapter: every nested skill call passes the same purchase gate. */
+export declare function createSkillRegistry(handlers: readonly SkillHandler[]): SkillRuntime;
+/** External buyer/seller communication remains ordinary A2A; only local skill dispatch changes. */
+export declare function skillScopedExecutor(runtime: SkillRuntime, signal?: AbortSignal): ExecuteOrder;